*/
/**
- * @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
*/
/**
- * @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
* 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
/**
- * 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
{
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};
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)
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__)
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;
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,
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 */
{
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");
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)
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
_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;
}
_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 */
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);
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);
} 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()
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 */
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 */
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
};
/**
- * 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);
/**
/**
* @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".
/**
- * 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
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;
/**
* @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
*/
*/
/**
- * 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
* 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 <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_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);
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
/**
- * 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;
* 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
*/
*/
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);
/**
* 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);
projects / framework / uifw / evas.git / commitdiff