enlightenment/efl
enlightenment
/
efl
8
7
Fork 14
Code Issues 13 Pull Requests 1 Projects Releases Wiki Activity

[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.



SVN revision: 60769
This commit is contained in:
Gustavo Lima Chaves 2011-06-28 17:43:44 +00:00
parent 5d473313b0
commit 003ab96f81
5 changed files with 709 additions and 261 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

136
legacy/evas/doc/examples.dox
View File

@ -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' <b>obscured regions</b>. 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

169
legacy/evas/src/examples/evas-events.c
View File

@ -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);

41
legacy/evas/src/examples/evas-stacking.c
View File

@ -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();

611
legacy/evas/src/lib/Evas.h
View File

@ -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.
*
* 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_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.
*
* 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. <p> 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 be tested.
* @param obj The object to retrieve focus information from.
* @return @c EINA_TRUE if the object has the focus, @c EINA_FALSE
* otherwise.
*
* If the passed object is the currently focused object 1 is returned,
* 0 otherwise.
* If the passed object is the currently focused one, @c EINA_TRUE is
* returned. @c EINA_FALSE is returned, 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.
*
* The events can be those from keyboard and mouse, if the object
* accepts these events.
* Objects also generate events on input (keyboard and mouse), if they
* accept them (are visible, focused, etc).
*
* 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_RESIZE, #EVAS_CALLBACK_RESTACK, #EVAS_CALLBACK_DEL,
* #EVAS_CALLBACK_HOLD, #EVAS_CALLBACK_CHANGED_SIZE_HINTS,
* #EVAS_CALLBACK_IMAGE_PRELOADED or #EVAS_CALLBACK_IMAGE_UNLOADED.
*
* #EVAS_CALLBACK_MOUSE_IN: event_info = pointer to Evas_Event_Mouse_In
* 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:
*
* 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_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: event_info = pointer to Evas_Event_Mouse_Out
* - #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.
*
* 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: @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 <b>passively grab the mouse</b> 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_DOWN: event_info = pointer to
* Evas_Event_Mouse_Down
* - #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).
*
* 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_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_UP: event_info = pointer to Evas_Event_Mouse_Up
* - #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).
*
* 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_MULTI_DOWN: @p event_info is a pointer to an
* #Evas_Event_Multi_Down struct
*
* #EVAS_CALLBACK_MOUSE_MOVE: event_info = pointer to Evas_Event_Mouse_Move
* - #EVAS_CALLBACK_MULTI_UP: @p event_info is a pointer to an
* #Evas_Event_Multi_Up struct
*
* This event is triggered by the mouse pointer moving while over an
* object or passively grabbed to an object.
* - #EVAS_CALLBACK_MULTI_MOVE: @p event_info is a pointer to an
* #Evas_Event_Multi_Move struct
*
* #EVAS_CALLBACK_MOUSE_WHEEL: event_info = pointer to
* Evas_Event_Mouse_Wheel
* - #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.
*
* This event is triggered by the mouse wheel being rolled while over
* an object or passively grabbed to an object.
* - #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_FREE: event_info = NULL
* - #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.
*
* 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_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_KEY_DOWN: event_info = pointer to Evas_Event_Key_Down
* - #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.
*
* 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_SHOW: @p event_info is @c NULL \n\n
* This event is triggered by the object being shown by
* evas_object_show().
*
* #EVAS_CALLBACK_KEY_UP: event_info = pointer to Evas_Event_Key_Up
* - #EVAS_CALLBACK_HIDE: @p event_info is @c NULL \n\n
* This event is triggered by an object being hidden by
* evas_object_hide().
*
* 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_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_FOCUS_IN: event_info = NULL
* - #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.
*
* This event is called when an object gains the focus. When the
* callback is called the object has already gained the focus.
* - #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_FOCUS_OUT: event_info = NULL
* - #EVAS_CALLBACK_DEL: @p event_info is @c 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_HOLD: @p event_info is a pointer to an
* #Evas_Event_Hold struct
*
* #EVAS_CALLBACK_SHOW: event_info = NULL
* - #EVAS_CALLBACK_CHANGED_SIZE_HINTS: @p event_info is @c NULL.
*
* This event is triggered by the object being shown by
* evas_object_show().
* - #EVAS_CALLBACK_IMAGE_PRELOADED: @p event_info is @c NULL.
*
* #EVAS_CALLBACK_HIDE: event_info = NULL
* - #EVAS_CALLBACK_IMAGE_UNLOADED: @p event_info is @c 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.
*
* 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.
* @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 false, events will be processed as normal.
* 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 @c EINA_FALSE, events will be processed on that
* object 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.
*
* 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.
* @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 false, events occurring on @p obj will be processed
* normally.
* 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 @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 @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.
*
* 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.
*
* 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'.
*
* Typical platforms are Linux frame buffer (Ecore_FB) and X server
* (Ecore_X) when using Evas with Ecore and Ecore_Evas.
*
* For a list of keynames for the Linux frame buffer, please refer to
* the Ecore_FB documentation.
* pressed (see @ref Evas_Keys for more information).
*
* @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.
* 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.
*
* @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.
*
* 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.
*
* Removes the grab on @p obj if @p keyname, @p modifiers, and @p not_modifiers
* match.
* @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.
*
* 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);

13
legacy/evas/src/lib/canvas/evas_object_main.c
View File

@ -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)
{