From d11dc67cf9aa5352005a8b19347b17f6b63308ca Mon Sep 17 00:00:00 2001 From: glima Date: Tue, 28 Jun 2011 17:43:44 +0000 Subject: [PATCH] [evas] Documenting more functions on Evas objects: - evas_object_event_callback_add - evas_object_event_callback_del_full - evas_object_focus_get - evas_object_focus_set - evas_object_key_grab - evas_object_key_ungrab - evas_object_pass_events_get - evas_object_pass_events_set - evas_object_precise_is_inside_get - evas_object_precise_is_inside_set - evas_object_propagate_events_get - evas_object_propagate_events_set - evas_object_repeat_events_get - evas_object_repeat_events_set Examples on them also follow. git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/evas@60769 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- doc/examples.dox | 136 +++++++- src/examples/evas-events.c | 169 +++++++++- src/examples/evas-stacking.c | 41 +++ src/lib/Evas.h | 659 +++++++++++++++++++++++--------------- src/lib/canvas/evas_object_main.c | 13 - 5 files changed, 733 insertions(+), 285 deletions(-) diff --git a/doc/examples.dox b/doc/examples.dox index 35866db..2a0c925 100644 --- a/doc/examples.dox +++ b/doc/examples.dox @@ -44,7 +44,127 @@ */ /** - * @page Example_Evas_Events Evas' canvas events example + * @page Example_Evas_Events Evas events (canvas and object ones) and some canvas operations example + * @dontinclude evas-events.c + * + * In this example we illustrate how to interact with canvas' (and + * its objects') events and other canvas operations. + * + * After we grab our canvas pointer, we registrate two event callbacks on it: + * @skip evas_event_callback_add(d.canvas, EVAS_CALLBACK_RENDER_FLUSH_PRE, + * @until two canvas event callbacks + * The first of them, whose code is + * @dontinclude evas-events.c + * @skip render flush callback + * @until } + * will be called whenever our canvas has to flush its rendering pipeline. + * In this example, two ways of observing that message which is printed in + * the cited callback are: + * - to resize the example's window (thus resizing the canvas' viewport) + * - let the animation run + * + * When one resizes the canvas, there's at least one operation it has + * to do which will require new calculation for rendering: the + * resizing of the background rectangle: + * @dontinclude evas-events.c + * @skip here just to keep + * @until } + * The animation we talked about comes from a timer we register just before + * we start the example's main loop: + * @dontinclude evas-events.c + * @skip d.resize_timer = ecore + * @until d.resize_timer = ecore + * being the timer's callback what follows: + * @dontinclude evas-events.c + * @skip put some action + * @until } + * As you see, the resizing of the image will also force the canvas to + * repaint itself, thus flushing the rendering pipeline whenever the + * timer ticks. When you start this example, this animation will be + * running, by default. To interact with the program, there's a + * command line interface, whose help string can be asked for with the + * 'h' key: + * @dontinclude evas-events.c + * @skip if (strcmp(ev->keyname, "h") == 0) + * @until } + * These are the commands the example will accept at any time, except + * when one triggers the 'f' one: + * @skip if (strcmp(ev->keyname, "f") == 0) + * @until } + * This command will exemplify evas_event_freeze(), which interrupts + * @b all input events processing for the canvas (in the example, just + * for 3 seconds). Try to issue events for it during that freeze time. + * The 'd' command will unregister those two canvas callbacks for you, + * so you won't see the messages about the focused object and the + * rendering process anymore: + * @dontinclude evas-events.c + * @skip if (strcmp(ev->keyname, "d") == 0) + * @until } + * The second of those callbacks has the following code: + * @dontinclude evas-events.c + * @skip called when our rectangle gets focus + * @until } + * It will take place whenever an object in the canvas receives + * focus. In this example, we use the focus to handle the input + * events: + * @skip so we get input events + * @until } + * The background rectangle is the chosen object to receive the + * focus. This also illustrates the use of + * evas_object_event_callback_add(), which registers an event callback + * on an Evas @b object (in this case, the event of a key being + * pressed down). On this callback, we examine each key pressed and, + * if they match one between the expected, we take some actions: + * @dontinclude evas-events.c + * @skip examine the keys pressed + * @until key grab + * We do so by examining the @c ev->keyname string (remember the event + * information struct for key down events is the #Evas_Event_Key_Down + * one). There's one more trick for grabbing input events on this + * example -- evas_object_key_grab(). The 'c' command will, when + * firstly used, @b unfocus the background rectangle. Unfocused + * objects on an Evas canvas will @b never receive key events. We + * grab, then, the keys we're interested at, to the object forcefully: + * @skip if (d.focus) + * @until got here by key grabs + * This shows how one can handle input not depending on focus issues + * -- you can grab them globally. Switch back and forth focus and + * forced key grabbing with the 'c' key, and observe the messages + * printed about the focused object. Observe, also, that we register + * two more @b object callbacks, this time on the image object + * (Enlightenment logo): + * @skip evas_object_show(d.img); + * @until mouse_out, NULL + * whose code blocks are + * @dontinclude evas-events.c + * @skip mouse enters the object's area + * @until mouse exits the object's area + * Experiment with moving the mouse pointer over the image, letting it + * enter and exit its area (stop the animation with 'a', for a better + * experience). When you start the example, Evas will consider this + * area by being the whole boundary rectangle around the picture. If + * you issue the 'p' command, though, you get a demonstration of Evas' + * precise point collision detection on objects: + * @dontinclude evas-events.c + * @skip if (strcmp(ev->keyname, "p") == 0) + * @until } + * With evas_object_precise_is_inside_get(), one can make Evas + * consider the transparent areas of an object (the middle of the + * logo's E letter, in the case) as not belonging to it when + * calculating mouse in/out/up/down events. To finish the example, try + * the command bound to Cotrol + 'o': + * @skip mods = evas_key_modifier_get(evas); + * @until end of obscured region command + * It exemplifies Evas' obscured regions. When firstly pressed, + * you'll get the same contents, in a region in the middle of the + * canvas, at the time the key was pressed, until you toggle the + * effect off again (make sure the animation is running on to get the + * idea better). When you toggle this effect off, we also demonstrate + * the use of evas_render_updates(), which will force immediate + * updates on the canvas rendering, bringing back the obscured + * region's contents to normal. + * + * What follows is the complete code for this example. * * @include evas-events.c * @example evas-events.c @@ -72,7 +192,7 @@ */ /** - * @page Example_Evas_Stacking Evas object stacking functions + * @page Example_Evas_Stacking Evas object stacking functions (and some event handling) * @dontinclude evas-stacking.c * * In this example, we illustrate how to stack objects in a custom @@ -113,6 +233,18 @@ * layers. For the initial layer (-1), it will never mess nor occlude * the others. * + * The last two commands available are "p" and "r", which will make + * the target rectangle to @b pass (ignore) and @b repeat the mouse + * events occurring on it (the commands will cycle through on and off + * states). This is demonstrated with the following + * #EVAS_CALLBACK_MOUSE_DOWN callback, registered on each of the + * colored rectangles: + * @dontinclude evas-stacking.c + * @skip static void + * @until } + * Try to change these properties on the three rectangles while + * experimenting with mouse clicks on their intersection region. + * * The full example follows. * * @include evas-stacking.c diff --git a/src/examples/evas-events.c b/src/examples/evas-events.c index 53ea940..e0ff211 100644 --- a/src/examples/evas-events.c +++ b/src/examples/evas-events.c @@ -1,6 +1,6 @@ /** - * Simple Evas example illustrating how to interact with canvas - * events and other canvas operations. + * Simple Evas example illustrating how to interact with canvas' (and + * its objects') events and other canvas operations. * * You'll need at least one engine built for it (excluding the buffer * one) and the png image loader also built. See stdout/stderr for @@ -30,9 +30,9 @@ struct test_data { Ecore_Evas *ee; Evas *canvas; - Eina_Bool obscured; Evas_Object *img, *bg; Ecore_Timer *resize_timer, *freeze_timer; + Eina_Bool obscured, focus; }; static struct test_data d = {0}; @@ -48,8 +48,8 @@ _canvas_resize_cb(Ecore_Evas *ee) evas_object_resize(d.bg, w, h); } -static void /* called when our rectangle gets focus */ +static void _object_focus_in_cb(void *data __UNUSED__, Evas *e, void *event_info) @@ -59,9 +59,12 @@ _object_focus_in_cb(void *data __UNUSED__, fprintf(stdout, "Let's recheck it: %s\n", evas_object_name_get(evas_focus_get(e))); + + fprintf(stdout, "And again: %s\n", evas_object_focus_get(event_info) ? + "OK!" : "Oops, something is bad."); } -static void +static void /* render flush callback */ _render_flush_cb(void *data __UNUSED__, Evas *e __UNUSED__, void *event_info __UNUSED__) @@ -69,8 +72,8 @@ _render_flush_cb(void *data __UNUSED__, fprintf(stdout, "Canvas is about to flush its rendering pipeline!\n"); } -static Eina_Bool /* put some action in the canvas */ +static Eina_Bool _resize_cb(void *data __UNUSED__) { int w, h, cw, ch; @@ -96,6 +99,25 @@ _thaw_cb(void *data __UNUSED__) return EINA_FALSE; /* do not re-issue the timer */ } +static void /* mouse enters the object's area */ +_on_mouse_in(void *data __UNUSED__, + Evas *evas __UNUSED__, + Evas_Object *o __UNUSED__, + void *einfo __UNUSED__) +{ + fprintf(stdout, "Enlightenment logo has had the mouse in.\n"); +} + +static void +_on_mouse_out(void *data __UNUSED__, + Evas *evas __UNUSED__, + Evas_Object *o __UNUSED__, + void *einfo __UNUSED__) +{ + fprintf(stdout, "Enlightenment logo has had the mouse out.\n"); +} /* mouse exits the object's area */ + +/* examine the keys pressed */ static void _on_keydown(void *data __UNUSED__, Evas *evas, @@ -105,7 +127,23 @@ _on_keydown(void *data __UNUSED__, const Evas_Modifier *mods; Evas_Event_Key_Down *ev = einfo; - fprintf(stdout, "we've got key input: %s\n", ev->keyname); + fprintf(stdout, "We've got key input: %s\n", ev->keyname); + fprintf(stdout, "It actually came from %s\n", d.focus ? + "focus" : "key grab"); + + if (strcmp(ev->keyname, "h") == 0) /* print help */ + { + fprintf(stdout, + "commands are:\n" + "\ta - toggle animation timer\n" + "\tc - cycle between focus and key grabs for key input\n" + "\td - delete canvas callbacks\n" + "\tf - freeze input for 3 seconds\n" + "\tp - toggle precise point collision detection on image\n" + "\tControl + o - add an obscured rectangle\n\n" + "\th - print help\n"); + return; + } if (strcmp(ev->keyname, "a") == 0) /* toggle animation timer */ { @@ -123,6 +161,85 @@ _on_keydown(void *data __UNUSED__, return; } + if (strcmp(ev->keyname, "c") == 0) /* cycle between focus and key + * grabs for key input */ + { + Eina_Bool ret; + Evas_Modifier_Mask mask = + evas_key_modifier_mask_get(d.canvas, "Control"); + + fprintf(stdout, "Switching to %s for key input\n", d.focus ? + "key grabs" : "focus"); + + if (d.focus) + { + evas_object_focus_set(d.bg, EINA_FALSE); + fprintf(stdout, "Focused object is now %s\n", + evas_focus_get(d.canvas) ? + "still valid! Something went wrong." : "none."); + + ret = evas_object_key_grab(d.bg, "a", 0, 0, EINA_TRUE); + if (!ret) + { + fprintf(stdout, "Something went wrong with key grabs.\n"); + goto c_end; + } + ret = evas_object_key_grab(d.bg, "c", 0, 0, EINA_TRUE); + if (!ret) + { + fprintf(stdout, "Something went wrong with key grabs.\n"); + goto c_end; + } + ret = evas_object_key_grab(d.bg, "d", 0, 0, EINA_TRUE); + if (!ret) + { + fprintf(stdout, "Something went wrong with key grabs.\n"); + goto c_end; + } + ret = evas_object_key_grab(d.bg, "f", 0, 0, EINA_TRUE); + if (!ret) + { + fprintf(stdout, "Something went wrong with key grabs.\n"); + goto c_end; + } + ret = evas_object_key_grab(d.bg, "p", 0, 0, EINA_TRUE); + if (!ret) + { + fprintf(stdout, "Something went wrong with key grabs.\n"); + goto c_end; + } + ret = evas_object_key_grab(d.bg, "o", mask, 0, EINA_TRUE); + if (!ret) + { + fprintf(stdout, "Something went wrong with key grabs.\n"); + goto c_end; + } + ret = evas_object_key_grab(d.bg, "h", 0, 0, EINA_TRUE); + if (!ret) + { + fprintf(stdout, "Something went wrong with key grabs.\n"); + goto c_end; + } + } + else /* got here by key grabs */ + { + evas_object_key_ungrab(d.bg, "a", 0, 0); + evas_object_key_ungrab(d.bg, "c", 0, 0); + evas_object_key_ungrab(d.bg, "d", 0, 0); + evas_object_key_ungrab(d.bg, "f", 0, 0); + evas_object_key_ungrab(d.bg, "p", 0, 0); + evas_object_key_ungrab(d.bg, "o", mask, 0); + evas_object_key_ungrab(d.bg, "h", 0, 0); + + evas_object_focus_set(d.bg, EINA_TRUE); + } + +c_end: + d.focus = !d.focus; + + return; + } + if (strcmp(ev->keyname, "d") == 0) /* delete canvas' callbacks */ { fprintf(stdout, "Deleting canvas event callbacks\n"); @@ -142,11 +259,23 @@ _on_keydown(void *data __UNUSED__, return; } + if (strcmp(ev->keyname, "p") == 0) /* toggle precise point + * collision detection */ + { + Eina_Bool precise = evas_object_precise_is_inside_get(d.img); + + fprintf(stdout, "Toggling precise point collision detection %s on" + " Enlightenment logo\n", precise ? "off" : "on"); + evas_object_precise_is_inside_set(d.img, !precise); + + return; + } + mods = evas_key_modifier_get(evas); if (evas_key_modifier_is_set(mods, "Control") && (strcmp(ev->keyname, "o") == 0)) /* add an obscured - * rectangle to the middle - * of the canvas */ + * rectangle to the middle + * of the canvas */ { fprintf(stdout, "Toggling obscured rectangle on canvas\n"); if (!d.obscured) @@ -175,13 +304,14 @@ _on_keydown(void *data __UNUSED__, EINA_LIST_FOREACH(updates, l, rect) { fprintf(stdout, "Rectangle (%d, %d, %d, %d) on canvas got a" - " rendering update.\n", rect->x, rect->y, rect->w, + " rendering update.\n", rect->x, rect->y, + rect->w, rect->h); } evas_render_updates_free(updates); } d.obscured = !d.obscured; - } + } /* end of obscured region command */ } int @@ -208,7 +338,7 @@ main(void) _render_flush_cb, NULL); if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE) { - fprintf(stderr, "ERROR: Callback registering failed! Abort!\n"); + fprintf(stderr, "ERROR: Callback registering failed! Aborting.\n"); goto panic; } @@ -216,7 +346,7 @@ main(void) _object_focus_in_cb, NULL); if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE) { - fprintf(stderr, "ERROR: Callback registering failed! Abort!\n"); + fprintf(stderr, "ERROR: Callback registering failed! Aborting.\n"); goto panic; } /* two canvas event callbacks */ @@ -227,9 +357,16 @@ main(void) evas_object_resize(d.bg, WIDTH, HEIGHT); /* covers full canvas */ evas_object_show(d.bg); - evas_object_focus_set(d.bg, EINA_TRUE); + evas_object_focus_set(d.bg, EINA_TRUE); /* so we get input events */ + d.focus = EINA_TRUE; + evas_object_event_callback_add( d.bg, EVAS_CALLBACK_KEY_DOWN, _on_keydown, NULL); + if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE) + { + fprintf(stderr, "ERROR: Callback registering failed! Aborting.\n"); + goto panic; + } d.img = evas_object_image_filled_add(d.canvas); evas_object_image_file_set(d.img, img_path, NULL); @@ -243,6 +380,10 @@ main(void) evas_object_move(d.img, 0, 0); evas_object_resize(d.img, WIDTH, HEIGHT); evas_object_show(d.img); + evas_object_event_callback_add( + d.img, EVAS_CALLBACK_MOUSE_IN, _on_mouse_in, NULL); + evas_object_event_callback_add( + d.img, EVAS_CALLBACK_MOUSE_OUT, _on_mouse_out, NULL); } d.resize_timer = ecore_timer_add(2, _resize_cb, NULL); diff --git a/src/examples/evas-stacking.c b/src/examples/evas-stacking.c index 559d2e9..e2e0b3b 100644 --- a/src/examples/evas-stacking.c +++ b/src/examples/evas-stacking.c @@ -37,6 +37,15 @@ struct test_data static struct test_data d = {0}; +static void +_on_mouse_down(void *data __UNUSED__, + Evas *evas __UNUSED__, + Evas_Object *o, + void *einfo __UNUSED__) +{ + fprintf(stdout, "Mouse down on rectangle %s!\n", evas_object_name_get(o)); +} + /* here just to keep our example's window size and background image's * size in synchrony */ static void @@ -68,6 +77,8 @@ _on_keydown(void *data __UNUSED__, "\tb - stack target rectangle one level below\n" "\tt - stack target rectangle up to the top of its layer\n" "\tm - stack target rectangle down to the bottom of its layer\n" + "\tp - toggle target rectangle's 'pass events' property\n" + "\tr - toggle target rectangle's 'repeat events' property\n" "\ts - print current stacking information\n" "\tl - change background rectangle's layer\n" "\th - print help\n"); @@ -153,6 +164,30 @@ _on_keydown(void *data __UNUSED__, return; } + if (strcmp(ev->keyname, "p") == 0) /* toggle pass events */ + { + Eina_Bool pass = evas_object_pass_events_get(d.rects[d.cur_rect]); + + evas_object_pass_events_set(d.rects[d.cur_rect], !pass); + + fprintf(stdout, "%s rectangle is now set to%s pass (ignore) events\n", + name, pass ? " NOT" : ""); + + return; + } + + if (strcmp(ev->keyname, "r") == 0) /* toggle repeat events */ + { + Eina_Bool repeat = evas_object_repeat_events_get(d.rects[d.cur_rect]); + + evas_object_repeat_events_set(d.rects[d.cur_rect], !repeat); + + fprintf(stdout, "%s rectangle is now set to%s repeat events\n", + name, repeat ? " NOT" : ""); + + return; + } + if (strcmp(ev->keyname, "a") == 0) /* stack target above */ { Evas_Object *neighbour = evas_object_above_get(d.rects[d.cur_rect]); @@ -252,6 +287,8 @@ main(void) evas_object_resize(d.rects[2], WIDTH / 2.2, WIDTH / 2.2); evas_object_move(d.rects[2], WIDTH / 6, WIDTH / 4.5); evas_object_show(d.rects[2]); + evas_object_event_callback_add( + d.rects[2], EVAS_CALLBACK_MOUSE_DOWN, _on_mouse_down, NULL); d.rects[1] = evas_object_rectangle_add(d.canvas); evas_object_name_set(d.rects[1], "green"); @@ -260,6 +297,8 @@ main(void) evas_object_resize(d.rects[1], WIDTH / 2.2, WIDTH / 2.2); evas_object_move(d.rects[1], WIDTH / 2.5, WIDTH / 7); evas_object_show(d.rects[1]); + evas_object_event_callback_add( + d.rects[1], EVAS_CALLBACK_MOUSE_DOWN, _on_mouse_down, NULL); d.rects[0] = evas_object_rectangle_add(d.canvas); evas_object_name_set(d.rects[0], "red"); @@ -268,6 +307,8 @@ main(void) evas_object_resize(d.rects[0], WIDTH / 2.2, WIDTH / 2.2); evas_object_move(d.rects[0], WIDTH / 3, WIDTH / 2.5); evas_object_show(d.rects[0]); + evas_object_event_callback_add( + d.rects[0], EVAS_CALLBACK_MOUSE_DOWN, _on_mouse_down, NULL); ecore_main_loop_begin(); diff --git a/src/lib/Evas.h b/src/lib/Evas.h index 11c1887..a283566 100644 --- a/src/lib/Evas.h +++ b/src/lib/Evas.h @@ -345,7 +345,8 @@ typedef enum _Evas_BiDi_Direction } Evas_BiDi_Direction; /** - * Identifier of callbacks to be used with object or canvas. + * Identifier of callbacks to be set for Evas canvases or Evas + * objects. * * @see evas_object_event_callback_add() * @see evas_event_callback_add() @@ -353,7 +354,7 @@ typedef enum _Evas_BiDi_Direction typedef enum _Evas_Callback_Type { /* - * The following events are only for use with objects + * The following events are only for use with Evas objects, with * evas_object_event_callback_add(): */ EVAS_CALLBACK_MOUSE_IN, /**< Mouse In Event */ @@ -378,10 +379,10 @@ typedef enum _Evas_Callback_Type EVAS_CALLBACK_DEL, /**< Object Being Deleted (called before Free) */ EVAS_CALLBACK_HOLD, /**< Events go on/off hold */ EVAS_CALLBACK_CHANGED_SIZE_HINTS, /**< Size hints changed event */ - EVAS_CALLBACK_IMAGE_PRELOADED, /**< Image as been preloaded */ + EVAS_CALLBACK_IMAGE_PRELOADED, /**< Image has been preloaded */ /* - * The following events are only for use with canvas + * The following events are only for use with Evas canvases, with * evas_event_callback_add(): */ EVAS_CALLBACK_CANVAS_FOCUS_IN, /**< Canvas got focus as a whole */ @@ -392,13 +393,12 @@ typedef enum _Evas_Callback_Type EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT, /**< Canvas object lost focus */ /* - * More object event types - see evas_object_event_callback_add(): + * More Evas object event types - see evas_object_event_callback_add(): */ - EVAS_CALLBACK_IMAGE_UNLOADED, /**< Image data has been unloaded (by some mechanims in evas that throws out original image data) */ + EVAS_CALLBACK_IMAGE_UNLOADED, /**< Image data has been unloaded (by some mechanims in Evas that throw out original image data) */ - /* the following id no event number, but a sentinel: */ - EVAS_CALLBACK_LAST /**< keep as last element/sentinel -- not really an event */ -} Evas_Callback_Type; /**< The type of event to trigger the callback */ + EVAS_CALLBACK_LAST /**< kept as last element/sentinel -- not really an event */ +} Evas_Callback_Type; /**< The types of events triggering a callback */ /** * Flags for Mouse Button events @@ -906,26 +906,30 @@ struct _Evas_Event_Hold /** Hold change event */ }; /** - * How mouse pointer should be handled by Evas. + * How the mouse pointer should be handled by Evas. + * + * In the mode #EVAS_OBJECT_POINTER_MODE_AUTOGRAB, when a mouse button + * is pressed down over an object and held, with the mouse pointer + * being moved outside of it, the pointer still behaves as being bound + * to that object, albeit out of its drawing region. When the button + * is released, the event will be fed to the object, that may check if + * the final position is over it or not and do something about it. * - * If #EVAS_OBJECT_POINTER_MODE_AUTOGRAB, then when mouse is down an - * object, then moves outside of it, the pointer still behaves as - * being bound to the object, albeit out of its drawing region. On - * mouse up, the event will be feed to the object, that may check if - * the final position is over or not and do something about it. + * In the mode #EVAS_OBJECT_POINTER_MODE_NOGRAB, the pointer will + * always be bound to the object right below it. * * @ingroup Evas_Object_Group_Extras */ typedef enum _Evas_Object_Pointer_Mode { EVAS_OBJECT_POINTER_MODE_AUTOGRAB, /**< default, X11-like */ - EVAS_OBJECT_POINTER_MODE_NOGRAB -} Evas_Object_Pointer_Mode; /**< How mouse pointer should be handled by 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_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); +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_Async_Events_Put_Cb)(void *target, Evas_Callback_Type type, void *event_info); /** @@ -1968,8 +1972,9 @@ EAPI Eina_Bool evas_pointer_inside_get (const Evas *e) EINA_WA /** * @defgroup Evas_Canvas_Events Canvas Events * - * Functions relating to canvas events, be they input (mice, - * keyboards, etc) or output ones (internal states changing, etc). + * Functions relating to canvas events, which are mainly reports on + * its internal states changing (an object got focused, the rendering + * is updated, etc). * * Some of the funcions in this group are exemplified @ref * Example_Evas_Events "here". @@ -2813,17 +2818,26 @@ EAPI const Eina_List *evas_object_clipees_get (const Evas_Object *obj /** - * Sets focus to the given object. + * Sets or unsets a given object as the currently focused one on its + * canvas. * * @param obj The object to be focused or unfocused. - * @param focus set or remove focus to the object. + * @param focus @c EINA_TRUE, to set it as focused or @c EINA_FALSE, + * to take away the focus from it. * - * Changing focus only affects where key events go. There can be only - * one object focused at any time.

If the parameter (@p focus) is - * set, the passed object will be set as the currently focused object. - * It will receive all keyboard events that are not exclusive key + * Changing focus only affects where (key) input events go. There can + * be only one object focused at any time. If @p focus is @c + * EINA_TRUE, @p obj will be set as the currently focused object and + * it will receive all keyboard events that are not exclusive key * grabs on other objects. * + * Example: + * @dontinclude evas-events.c + * @skip evas_object_focus_set + * @until evas_object_focus_set + * + * See the full example @ref Example_Evas_Events "here". + * * @see evas_object_focus_get * @see evas_focus_get * @see evas_object_key_grab @@ -2832,19 +2846,26 @@ EAPI const Eina_List *evas_object_clipees_get (const Evas_Object *obj EAPI void evas_object_focus_set (Evas_Object *obj, Eina_Bool focus) EINA_ARG_NONNULL(1); /** - * Test if the object has focus. + * Retrieve whether an object has the focus. + * + * @param obj The object to retrieve focus information from. + * @return @c EINA_TRUE if the object has the focus, @c EINA_FALSE + * otherwise. * - * @param obj The object to be tested. + * If the passed object is the currently focused one, @c EINA_TRUE is + * returned. @c EINA_FALSE is returned, otherwise. * - * If the passed object is the currently focused object 1 is returned, - * 0 otherwise. + * Example: + * @dontinclude evas-events.c + * @skip And again + * @until something is bad + * + * See the full example @ref Example_Evas_Events "here". * * @see evas_object_focus_set * @see evas_focus_get * @see evas_object_key_grab * @see evas_object_key_ungrab - * - * @return 1 if the object has the focus, 0 otherwise. */ EAPI Eina_Bool evas_object_focus_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; @@ -3387,12 +3408,15 @@ EAPI Evas_Object *evas_object_below_get (const Evas_Object *obj /** * @defgroup Evas_Object_Group_Events Object Events * - * Objects generates events when they are moved, resized, when their + * Objects generate events when they are moved, resized, when their * visibility change, when they are deleted and so on. These methods - * will allow one to handle such events. + * allow one to be notified about and to handle such events. + * + * Objects also generate events on input (keyboard and mouse), if they + * accept them (are visible, focused, etc). * - * The events can be those from keyboard and mouse, if the object - * accepts these events. + * Examples on this group of functions can be found @ref + * Example_Evas_Stacking "here" and @ref Example_Evas_Events "here". * * @ingroup Evas_Object_Group */ @@ -3403,7 +3427,7 @@ EAPI Evas_Object *evas_object_below_get (const Evas_Object *obj */ /** - * Add a callback function to an object + * Add (register) a callback function to a given Evas object event. * * @param obj Object to attach a callback to * @param type The type of event that will trigger the callback @@ -3418,161 +3442,174 @@ EAPI Evas_Object *evas_object_below_get (const Evas_Object *obj * determine the nature of the error, if any, and the program should * sensibly try and recover. * - * The function will be passed the pointer @p data when it is - * called. A callback function must look like this: - * - * @code - * void callback (void *data, Evas *e, Evas_Object *obj, void *event_info); - * @endcode - * - * The first parameter @p data in this function will be the same value - * passed to evas_object_event_callback_add() as the @p data - * parameter. The second parameter is a convenience for the programmer - * to know what evas canvas the event occurred on. The third parameter - * @p obj is the Object handle on which the event occurred. The foruth - * parameter @p event_info is a pointer to a data structure that may - * or may not be passed to the callback, depending on the event type - * that triggered the callback. + * A callback function must have the ::Evas_Object_Event_Cb prototype + * definition. The first parameter (@p data) in this definition will + * have the same value passed to evas_object_event_callback_add() as + * the @p data parameter, at runtime. The second parameter @p e is the + * canvas pointer on which the event occurred. The third parameter is + * a pointer to the object on which event occurred. Finally, the + * fourth parameter @p event_info is a pointer to a data structure + * that may or may not be passed to the callback, depending on the + * event type that triggered the callback. This is so because some + * events don't carry extra context with them, but others do. * * The event type @p type to trigger the function may be one of * #EVAS_CALLBACK_MOUSE_IN, #EVAS_CALLBACK_MOUSE_OUT, * #EVAS_CALLBACK_MOUSE_DOWN, #EVAS_CALLBACK_MOUSE_UP, * #EVAS_CALLBACK_MOUSE_MOVE, #EVAS_CALLBACK_MOUSE_WHEEL, - * #EVAS_CALLBACK_FREE, #EVAS_CALLBACK_KEY_DOWN, #EVAS_CALLBACK_KEY_UP, + * #EVAS_CALLBACK_MULTI_DOWN, #EVAS_CALLBACK_MULTI_UP, + * #EVAS_CALLBACK_MULTI_MOVE, #EVAS_CALLBACK_FREE, + * #EVAS_CALLBACK_KEY_DOWN, #EVAS_CALLBACK_KEY_UP, * #EVAS_CALLBACK_FOCUS_IN, #EVAS_CALLBACK_FOCUS_OUT, * #EVAS_CALLBACK_SHOW, #EVAS_CALLBACK_HIDE, #EVAS_CALLBACK_MOVE, - * #EVAS_CALLBACK_RESIZE or #EVAS_CALLBACK_RESTACK. - * This determines the kind of event that will trigger the callback to - * be called. The @p event_info pointer passed to the callback will - * be one of the following, depending on the event triggering it: - * - * #EVAS_CALLBACK_MOUSE_IN: event_info = pointer to Evas_Event_Mouse_In - * - * This event is triggered when the mouse pointer enters the region of - * the object @p obj. This may occur by the mouse pointer being moved - * by evas_event_feed_mouse_move() or - * evas_event_feed_mouse_move_data() calls, or by the object being - * shown, raised, moved, resized, or other objects being moved out of - * the way, hidden, lowered or moved out of the way. - * - * #EVAS_CALLBACK_MOUSE_OUT: event_info = pointer to Evas_Event_Mouse_Out - * - * This event is triggered exactly like #EVAS_CALLBACK_MOUSE_IN is, but - * occurs when the mouse pointer exits an object. Note that no out - * events will be reported if the mouse pointer is implicitly grabbed - * to an object (the mouse buttons are down at all and any were - * pressed on that object). An out event will be reported as soon as - * the mouse is no longer grabbed (no mouse buttons are - * depressed). Out events will be reported once all buttons are - * released, if the mouse has left the object. - * - * #EVAS_CALLBACK_MOUSE_DOWN: event_info = pointer to - * Evas_Event_Mouse_Down - * - * This event is triggered by a mouse button being depressed while - * over an object. If pointermode is EVAS_OBJECT_POINTER_MODE_AUTOGRAB - * (default) this causes this object to passively grab the mouse until - * all mouse buttons have been released. That means if this mouse - * button is the first to be pressed, all future mouse events will be - * reported to only this object until no buttons are down. That - * includes mouse move events, in and out events, and further button - * presses. When all buttons are released, event propagation occurs as - * normal. - * - * #EVAS_CALLBACK_MOUSE_UP: event_info = pointer to Evas_Event_Mouse_Up - * - * This event is triggered by a mouse button being released while over - * an object or when passively grabbed to an object. If this is the - * last mouse button to be raised on an object then the passive grab - * is released and event processing will continue as normal. - * - * #EVAS_CALLBACK_MOUSE_MOVE: event_info = pointer to Evas_Event_Mouse_Move - * - * This event is triggered by the mouse pointer moving while over an - * object or passively grabbed to an object. - * - * #EVAS_CALLBACK_MOUSE_WHEEL: event_info = pointer to - * Evas_Event_Mouse_Wheel - * - * This event is triggered by the mouse wheel being rolled while over - * an object or passively grabbed to an object. - * - * #EVAS_CALLBACK_FREE: event_info = NULL - * - * This event is triggered just before Evas is about to free all - * memory used by an object and remove all references to it. This is - * useful for programs to use if they attached data to an object and - * want to free it when the object is deleted. The object is still - * valid when this callback is called, but after this callback - * returns, there is no guarantee on the object's validity. - * - * #EVAS_CALLBACK_KEY_DOWN: event_info = pointer to Evas_Event_Key_Down - * - * This callback is called when a key is pressed and the focus is on - * the object, or a key has been grabbed to a particular object which - * wants to intercept the key press regardless of what object has the - * focus. - * - * #EVAS_CALLBACK_KEY_UP: event_info = pointer to Evas_Event_Key_Up - * - * This callback is called when a key is released and the focus is on - * the object, or a key has been grabbed to a particular object which - * wants to intercept the key release regardless of what object has - * the focus. - * - * #EVAS_CALLBACK_FOCUS_IN: event_info = NULL + * #EVAS_CALLBACK_RESIZE, #EVAS_CALLBACK_RESTACK, #EVAS_CALLBACK_DEL, + * #EVAS_CALLBACK_HOLD, #EVAS_CALLBACK_CHANGED_SIZE_HINTS, + * #EVAS_CALLBACK_IMAGE_PRELOADED or #EVAS_CALLBACK_IMAGE_UNLOADED. + * + * This determines the kind of event that will trigger the callback. + * What follows is a list explaining better the nature of each type of + * event, along with their associated @p event_info pointers: + * + * - #EVAS_CALLBACK_MOUSE_IN: @p event_info is a pointer to an + * #Evas_Event_Mouse_In struct\n\n + * This event is triggered when the mouse pointer enters the area + * (not shaded by other objects) of the object @p obj. This may + * occur by the mouse pointer being moved by + * evas_event_feed_mouse_move() calls, or by the object being shown, + * raised, moved, resized, or other objects being moved out of the + * way, hidden or lowered, whatever may cause the mouse pointer to + * get on top of @p obj, having been on top of another object + * previously. + * + * - #EVAS_CALLBACK_MOUSE_OUT: @p event_info is a pointer to an + * #Evas_Event_Mouse_Out struct\n\n + * This event is triggered exactly like #EVAS_CALLBACK_MOUSE_IN is, + * but it occurs when the mouse pointer exits an object's area. Note + * that no mouse out events will be reported if the mouse pointer is + * implicitly grabbed to an object (mouse buttons are down, having + * been pressed while the pointer was over that object). In these + * cases, mouse out events will be reported once all buttons are + * released, if the mouse pointer has left the object's area. The + * indirect ways of taking off the mouse pointer from an object, + * like cited above, for #EVAS_CALLBACK_MOUSE_IN, also apply here, + * naturally. + * + * - #EVAS_CALLBACK_MOUSE_DOWN: @p event_info is a pointer to an + * #Evas_Event_Mouse_Down struct\n\n + * This event is triggered by a mouse button being pressed while the + * mouse pointer is over an object. If the pointer mode for Evas is + * #EVAS_OBJECT_POINTER_MODE_AUTOGRAB (default), this causes this + * object to passively grab the mouse until all mouse buttons + * have been released: all future mouse events will be reported to + * only this object until no buttons are down. That includes mouse + * move events, mouse in and mouse out events, and further button + * presses. When all buttons are released, event propagation will + * occur as normal (see #Evas_Object_Pointer_Mode). + * + * - #EVAS_CALLBACK_MOUSE_UP: @p event_info is a pointer to an + * #Evas_Event_Mouse_Up struct\n\n + * This event is triggered by a mouse button being released while + * the mouse pointer is over an object's area (or when passively + * grabbed to an object). + * + * - #EVAS_CALLBACK_MOUSE_MOVE: @p event_info is a pointer to an + * #Evas_Event_Mouse_Move struct\n\n + * This event is triggered by the mouse pointer being moved while + * over an object's area (or while passively grabbed to an object). + * + * - #EVAS_CALLBACK_MOUSE_WHEEL: @p event_info is a pointer to an + * #Evas_Event_Mouse_Wheel struct\n\n + * This event is triggered by the mouse wheel being rolled while the + * mouse pointer is over an object (or passively grabbed to an + * object). + * + * - #EVAS_CALLBACK_MULTI_DOWN: @p event_info is a pointer to an + * #Evas_Event_Multi_Down struct + * + * - #EVAS_CALLBACK_MULTI_UP: @p event_info is a pointer to an + * #Evas_Event_Multi_Up struct + * + * - #EVAS_CALLBACK_MULTI_MOVE: @p event_info is a pointer to an + * #Evas_Event_Multi_Move struct + * + * - #EVAS_CALLBACK_FREE: @p event_info is @c NULL \n\n + * This event is triggered just before Evas is about to free all + * memory used by an object and remove all references to it. This is + * useful for programs to use if they attached data to an object and + * want to free it when the object is deleted. The object is still + * valid when this callback is called, but after it returns, there + * is no guarantee on the object's validity. + * + * - #EVAS_CALLBACK_KEY_DOWN: @p event_info is a pointer to an + * #Evas_Event_Key_Down struct\n\n + * This callback is called when a key is pressed and the focus is on + * the object, or a key has been grabbed to a particular object + * which wants to intercept the key press regardless of what object + * has the focus. + * + * - #EVAS_CALLBACK_KEY_UP: @p event_info is a pointer to an + * #Evas_Event_Key_Up struct \n\n + * This callback is called when a key is released and the focus is + * on the object, or a key has been grabbed to a particular object + * which wants to intercept the key release regardless of what + * object has the focus. + * + * - #EVAS_CALLBACK_FOCUS_IN: @p event_info is @c NULL \n\n + * This event is called when an object gains the focus. When it is + * called the object has already gained the focus. + * + * - #EVAS_CALLBACK_FOCUS_OUT: @p event_info is @c NULL \n\n + * This event is triggered when an object loses the focus. When it + * is called the object has already lost the focus. + * + * - #EVAS_CALLBACK_SHOW: @p event_info is @c NULL \n\n + * This event is triggered by the object being shown by + * evas_object_show(). + * + * - #EVAS_CALLBACK_HIDE: @p event_info is @c NULL \n\n + * This event is triggered by an object being hidden by + * evas_object_hide(). + * + * - #EVAS_CALLBACK_MOVE: @p event_info is @c NULL \n\n + * This event is triggered by an object being + * moved. evas_object_move() can trigger this, as can any + * object-specific manipulations that would mean the object's origin + * could move. + * + * - #EVAS_CALLBACK_RESIZE: @p event_info is @c NULL \n\n + * This event is triggered by an object being resized. Resizes can + * be triggered by evas_object_resize() or by any object-specific + * calls that may cause the object to resize. + * + * - #EVAS_CALLBACK_RESTACK: @p event_info is @c NULL \n\n + * This event is triggered by an object being re-stacked. Stacking + * changes can be triggered by + * evas_object_stack_below()/evas_object_stack_above() and others. + * + * - #EVAS_CALLBACK_DEL: @p event_info is @c NULL. + * + * - #EVAS_CALLBACK_HOLD: @p event_info is a pointer to an + * #Evas_Event_Hold struct + * + * - #EVAS_CALLBACK_CHANGED_SIZE_HINTS: @p event_info is @c NULL. + * + * - #EVAS_CALLBACK_IMAGE_PRELOADED: @p event_info is @c NULL. + * + * - #EVAS_CALLBACK_IMAGE_UNLOADED: @p event_info is @c NULL. * - * This event is called when an object gains the focus. When the - * callback is called the object has already gained the focus. - * - * #EVAS_CALLBACK_FOCUS_OUT: event_info = NULL - * - * This event is triggered by an object losing the focus. When the - * callback is called the object has already lost the focus. - * - * #EVAS_CALLBACK_SHOW: event_info = NULL - * - * This event is triggered by the object being shown by - * evas_object_show(). - * - * #EVAS_CALLBACK_HIDE: event_info = NULL - * - * This event is triggered by an object being hidden by - * evas_object_hide(). - * - * #EVAS_CALLBACK_MOVE: event_info = NULL - * - * This event is triggered by an object being - * moved. evas_object_move() can trigger this, as can any - * object-specific manipulations that would mean the object's origin - * could move. - * - * #EVAS_CALLBACK_RESIZE: event_info = NULL - * - * This event is triggered by an object being resized. Resizes can be - * triggered by evas_object_resize() or by any object-specific calls - * that may cause the object to resize. + * @note Be careful not to add the same callback multiple times, if + * that's not what you want, because Evas won't check if a callback + * existed before exactly as the one being registered (and thus, call + * it more than once on the event, in this case). This would make + * sense if you passed different functions and/or callback data, only. * * Example: - * @code - * extern Evas_Object *object; - * extern void *my_data; - * void down_callback(void *data, Evas *e, Evas_Object *obj, void *event_info); - * void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info); + * @dontinclude evas-events.c + * @skip evas_object_event_callback_add( + * @until } + * + * See the full example @ref Example_Evas_Events "here". * - * evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_UP, up_callback, my_data); - * if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE) - * { - * fprintf(stderr, "ERROR: Callback registering failed! Abort!\n"); - * exit(-1); - * } - * evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_DOWN, down_callback, my_data); - * if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE) - * { - * fprintf(stderr, "ERROR: Callback registering failed! Abort!\n"); - * exit(-1); - * } - * @endcode */ EAPI void evas_object_event_callback_add (Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3); @@ -3603,21 +3640,27 @@ EAPI Evas_Object *evas_object_below_get (const Evas_Object *obj EAPI void *evas_object_event_callback_del (Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func) EINA_ARG_NONNULL(1, 3); /** - * Delete a callback function from an object + * Delete (unregister) a callback function registered to a given + * Evas object event. * * @param obj Object to remove a callback from * @param type The type of event that was triggering the callback - * @param func The function that was to be called when the event was triggered + * @param func The function that was to be called when the event was + * triggered * @param data The data pointer that was to be passed to the callback * @return The data pointer that was to be passed to the callback * * This function removes the most recently added callback from the - * object @p obj which was triggered by the event type @p type and was - * calling the function @p func with data @p data when triggered. If + * object @p obj, which was triggered by the event type @p type and was + * calling the function @p func with data @p data, when triggered. If * the removal is successful it will also return the data pointer that * was passed to evas_object_event_callback_add() (that will be the * same as the parameter) when the callback was added to the - * object. If not successful NULL will be returned. + * object. In errors, @c NULL will be returned. + * + * @note For deletion of Evas object events callbacks filtering by + * just type and function pointer, user + * evas_object_event_callback_del(). * * Example: * @code @@ -3632,70 +3675,120 @@ EAPI void *evas_object_event_callback_del_full(Evas_Object *obj, Eva /** - * Set an object's pass events state. - * @param obj the Evas object - * @param pass whether to pass events or not + * Set whether an Evas object is to pass (ignore) events. + * + * @param obj the Evas object to operate on + * @param pass whether @p obj is to pass events (@c EINA_TRUE) or not + * (@c EINA_FALSE) + * + * If @p pass is @c EINA_TRUE, it will make events on @p obj to be @b + * ignored. They will be triggered on the @b next lower object (that + * is not set to pass events), instead (see evas_object_below_get()). * - * If @p pass is true, this will cause events on @p obj to be ignored. - * They will be triggered on the next lower object (that is not set to - * pass events) instead. + * If @p pass is @c EINA_FALSE, events will be processed on that + * object as normal. * - * If @p pass is false, events will be processed as normal. + * @see evas_object_pass_events_get() for an example + * @see evas_object_repeat_events_set() + * @see evas_object_propagate_events_set() */ EAPI void evas_object_pass_events_set (Evas_Object *obj, Eina_Bool pass) EINA_ARG_NONNULL(1); /** - * Determine whether an object is set to pass events. - * @param obj - * @return pass events state + * Determine whether an object is set to pass (ignore) events. + * + * @param obj the Evas object to get information from. + * @return pass whether @p obj is set to pass events (@c EINA_TRUE) or not + * (@c EINA_FALSE) + * + * Example: + * @dontinclude evas-stacking.c + * @skip if (strcmp(ev->keyname, "p") == 0) + * @until } + * + * See the full @ref Example_Evas_Stacking "example". + * + * @see evas_object_pass_events_set() + * @see evas_object_repeat_events_get() + * @see evas_object_propagate_events_get() */ EAPI Eina_Bool evas_object_pass_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; /** - * Set an object's repeat events state. - * @param obj the object - * @param repeat wheter to repeat events or not + * Set whether an Evas object is to repeat events. + * + * @param obj the Evas object to operate on + * @param repeat whether @p obj is to repeat events (@c EINA_TRUE) or not + * (@c EINA_FALSE) * - * If @p repeat is true, this will cause events on @p obj to trigger - * callbacks, but also to be repeated on the next lower object in the - * stack. + * If @p repeat is @c EINA_TRUE, it will make events on @p obj to also + * be repeated for the @b next lower object in the objects' stack (see + * see evas_object_below_get()). * - * If @p repeat is false, events occurring on @p obj will be processed - * normally. + * If @p repeat is @c EINA_FALSE, events occurring on @p obj will be + * processed only on it. + * + * Example: + * @dontinclude evas-stacking.c + * @skip if (strcmp(ev->keyname, "r") == 0) + * @until } + * + * See the full @ref Example_Evas_Stacking "example". + * + * @see evas_object_repeat_events_get() + * @see evas_object_pass_events_get() + * @see evas_object_propagate_events_get() */ EAPI void evas_object_repeat_events_set (Evas_Object *obj, Eina_Bool repeat) EINA_ARG_NONNULL(1); /** * Determine whether an object is set to repeat events. - * @param obj - * @return repeat events state + * + * @param obj the given Evas object pointer + * @retrieve whether @p obj is set to repeat events (@c EINA_TRUE) + * or not (@c EINA_FALSE) + * + * @see evas_object_repeat_events_set() for an example + * @see evas_object_pass_events_set() + * @see evas_object_propagate_events_set() */ EAPI Eina_Bool evas_object_repeat_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; /** - * Set whether events on a smart member object should propagate to its - * parent. + * Set whether events on a smart object's member should get propagated + * up to its parent. * - * @param obj the smart member object - * @param prop wheter to propagate events or not + * @param obj the smart object's child to operate on + * @param prop whether to propagate events (@c EINA_TRUE) or not (@c + * EINA_FALSE) * - * This function has no effect if @p obj is not a member of a smart + * This function has @b no effect if @p obj is not a member of a smart * object. * - * If @p prop is true, events occurring on this object will propagate on - * to the smart object of which @p obj is a member. - * - * If @p prop is false, events for which callbacks are set on the member - * object, @p obj, will not be passed on to the parent smart object. + * If @p prop is @c EINA_TRUE, events occurring on this object will be + * propagated on to the smart object of which @p obj is a member. If + * @p prop is @c EINA_FALSE, events occurring on this object will @b + * not be propagated on to the smart object of which @p obj is a + * member. The default value is @c EINA_TRUE. * - * The default value is true. + * @see evas_object_event_callback_add() + * @see evas_object_propagate_events_get() + * @see evas_object_repeat_events_get() + * @see evas_object_pass_events_get() */ EAPI void evas_object_propagate_events_set (Evas_Object *obj, Eina_Bool prop) EINA_ARG_NONNULL(1); /** - * Determine whether an object is set to propagate events. - * @param obj - * @return propagate events state + * Retrieve whether an Evas object is set to propagate events. + * + * @param obj the given Evas object pointer + * @return whether @p obj is set to propagate events (@c EINA_TRUE) + * or not (@c EINA_FALSE) + * + * @see evas_object_event_callback_add() + * @see evas_object_propagate_events_set() + * @see evas_object_repeat_events_set() + * @see evas_object_pass_events_set() */ EAPI Eina_Bool evas_object_propagate_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; @@ -4645,6 +4738,9 @@ EAPI void evas_object_size_hint_padding_set (Evas_Object *obj, Evas * Miscellaneous functions that also apply to any object, but are less * used or not implemented by all objects. * + * Examples on this group of functions can be found @ref + * Example_Evas_Stacking "here" and @ref Example_Evas_Events "here". + * * @ingroup Evas_Object_Group */ @@ -4847,7 +4943,46 @@ EAPI void evas_object_render_op_set (Evas_Object *ob */ EAPI Evas_Render_Op evas_object_render_op_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; +/** + * Set whether to use precise (usually expensive) point collision + * detection for a given Evas object. + * + * @param obj The given object. + * @param precise whether to use precise point collision detection or + * not The default value is false. + * + * Use this function to make Evas treat objects' transparent areas as + * @b not belonging to it with regard to mouse pointer events. By + * default, all of the object's boundary rectangle will be taken in + * account for them. + * + * @warning By using precise point collision detection you'll be + * making Evas more resource intensive. + * + * Example code follows. + * @dontinclude evas-events.c + * @skip if (strcmp(ev->keyname, "p") == 0) + * @until } + * + * See the full example @ref Example_Evas_Events "here". + * + * @see evas_object_precise_is_inside_get() + * @ingroup Evas_Object_Group_Extras + */ EAPI void evas_object_precise_is_inside_set(Evas_Object *obj, Eina_Bool precise) EINA_ARG_NONNULL(1); + +/** + * Determine whether an object is set to use precise point collision + * detection. + * + * @param obj The given object. + * @return whether @p obj is set to use precise point collision + * detection or not The default value is false. + * + * @see evas_object_precise_is_inside_set() for an example + * + * @ingroup Evas_Object_Group_Extras + */ EAPI Eina_Bool evas_object_precise_is_inside_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; EAPI void evas_object_static_clip_set (Evas_Object *obj, Eina_Bool is_static_clip) EINA_ARG_NONNULL(1); @@ -9459,63 +9594,75 @@ EAPI Evas_Modifier_Mask evas_key_modifier_mask_get (const Evas *e, const c /** * Requests @p keyname key events be directed to @p obj. * - * Key grabs allow an object to receive key events for specific key - * strokes even if another object has focus. If the grab is - * non-exclusive then all objects that have grabs on the key will get - * the event, however if the grab is exclusive, no other object can - * get a grab on the key and only that object will get the event. + * @param obj the object to direct @p keyname events to. + * @param keyname the key to request events for. + * @param modifiers a mask of modifiers that must be present to + * trigger the event. + * @param not_modifiers a mask of modifiers that must @b not be present + * to trigger the event. + * @param exclusive request that the @p obj is the only object + * receiving the @p keyname events. + * @return @c EINA_TRUE, if the call succeeded, @c EINA_FALSE otherwise. + * + * Key grabs allow one or more objects to receive key events for + * specific key strokes even if other objects have focus. Whenever a + * key is grabbed, only the objects grabbing it will get the events + * for the given keys. * * @p keyname is a platform dependent symbolic name for the key - * pressed. It is sometimes possible to convert the string to an - * ASCII value of the key, but not always for example the enter key - * may be returned as the string 'Enter'. + * pressed (see @ref Evas_Keys for more information). * - * Typical platforms are Linux frame buffer (Ecore_FB) and X server - * (Ecore_X) when using Evas with Ecore and Ecore_Evas. + * @p modifiers and @p not_modifiers are bit masks of all the + * modifiers that must and mustn't, respectively, be pressed along + * with @p keyname key in order to trigger this new key + * grab. Modifiers can be things such as Shift and Ctrl as well as + * user defigned types via evas_key_modifier_add(). Retrieve them with + * evas_key_modifier_mask_get() or use @c 0 for empty masks. * - * For a list of keynames for the Linux frame buffer, please refer to - * the Ecore_FB documentation. + * @p exclusive will make the given object the only one permitted to + * grab the given key. If given @c EINA_TRUE, subsequent calls on this + * function with different @p obj arguments will fail, unless the key + * is ungrabbed again. * - * @p modifiers and @p not_modifiers are bit masks of all the - * modifiers that are required and not required respectively for the - * new grab. Modifiers can be things such as shift and ctrl as well - * as user defigned types via evas_key_modifier_add. + * Example code follows. + * @dontinclude evas-events.c + * @skip if (d.focus) + * @until else + * + * See the full example @ref Example_Evas_Events "here". * * @see evas_object_key_ungrab * @see evas_object_focus_set * @see evas_object_focus_get * @see evas_focus_get * @see evas_key_modifier_add - * - * @param obj the object to direct @p keyname events to. - * @param keyname the key to request events for. - * @param modifiers a mask of modifiers that should be present to - * trigger the event. - * @param not_modifiers a mask of modifiers that should not be present - * to trigger the event. - * @param exclusive request that the @p obj is the only object - * receiving the @p keyname events. - * @return Boolean indicating whether the grab succeeded */ EAPI Eina_Bool evas_object_key_grab (Evas_Object *obj, const char *keyname, Evas_Modifier_Mask modifiers, Evas_Modifier_Mask not_modifiers, Eina_Bool exclusive) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2); /** - * Request that the grab on @p obj be removed. + * Removes the grab on @p keyname key events by @p obj. + * + * @param obj the object that has an existing key grab. + * @param keyname the key the grab is set for. + * @param modifiers a mask of modifiers that must be present to + * trigger the event. + * @param not_modifiers a mask of modifiers that must not not be + * present to trigger the event. + * + * Removes a key grab on @p obj if @p keyname, @p modifiers, and @p + * not_modifiers match. * - * Removes the grab on @p obj if @p keyname, @p modifiers, and @p not_modifiers - * match. + * Example code follows. + * @dontinclude evas-events.c + * @skip got here by key grabs + * @until } + * + * See the full example @ref Example_Evas_Events "here". * * @see evas_object_key_grab * @see evas_object_focus_set * @see evas_object_focus_get * @see evas_focus_get - * - * @param obj the object that has an existing grab. - * @param keyname the key the grab is for. - * @param modifiers a mask of modifiers that should be present to - * trigger the event. - * @param not_modifiers a mask of modifiers that should not be present - * to trigger the event. */ EAPI void evas_object_key_ungrab (Evas_Object *obj, const char *keyname, Evas_Modifier_Mask modifiers, Evas_Modifier_Mask not_modifiers) EINA_ARG_NONNULL(1, 2); diff --git a/src/lib/canvas/evas_object_main.c b/src/lib/canvas/evas_object_main.c index 9627a37..a35dc20 100644 --- a/src/lib/canvas/evas_object_main.c +++ b/src/lib/canvas/evas_object_main.c @@ -1259,13 +1259,6 @@ evas_object_type_get(const Evas_Object *obj) return obj->type; } -/** - * Set whether to use a precise (usually expensive) point collision detection. - * @param obj The given object. - * @param precise wheter to use a precise point collision detection or not - * The default value is false. - * @ingroup Evas_Object_Group_Extras - */ EAPI void evas_object_precise_is_inside_set(Evas_Object *obj, Eina_Bool precise) { @@ -1275,12 +1268,6 @@ evas_object_precise_is_inside_set(Evas_Object *obj, Eina_Bool precise) obj->precise_is_inside = precise; } -/** - * Determine whether an object is set to use a precise point collision - * detection. - * @param obj The given object. - * @ingroup Evas_Object_Group_Extras - */ EAPI Eina_Bool evas_object_precise_is_inside_get(const Evas_Object *obj) { -- 2.7.4