Functions that allows finding objects by their position, name or other properties. More...

Functions

Evas_Objectevas_focus_get (const Evas *e)
 Retrieve the object that currently has focus.
Evas_Objectevas_object_name_find (const Evas *e, const char *name)
 Retrieves the object on the given evas with the given name.
Evas_Objectevas_object_name_child_find (const Evas_Object *obj, const char *name, int recurse)
 Retrieves the object from children of the given object with the given name.
Evas_Objectevas_object_top_at_xy_get (const Evas *e, Evas_Coord x, Evas_Coord y, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects)
 Retrieve the Evas object stacked at the top of a given position in a canvas.
Evas_Objectevas_object_top_at_pointer_get (const Evas *e)
 Retrieve the Evas object stacked at the top at the position of the mouse cursor, over a given canvas.
Evas_Objectevas_object_top_in_rectangle_get (const Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects)
 Retrieve the Evas object stacked at the top of a given rectangular region in a canvas.
Eina_List * evas_objects_at_xy_get (const Evas *e, Evas_Coord x, Evas_Coord y, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects)
 Retrieve a list of Evas objects lying over a given position in a canvas.
Eina_List * evas_objects_in_rectangle_get (const Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects)
 Retrieves the objects in the given rectangle region.
Evas_Objectevas_object_bottom_get (const Evas *e)
 Get the lowest (stacked) Evas object on the canvas e.
Evas_Objectevas_object_top_get (const Evas *e)
 Get the highest (stacked) Evas object on the canvas e.

Detailed Description

Functions that allows finding objects by their position, name or other properties.

Function Documentation

Evas_Object* evas_focus_get ( const Evas e)

Retrieve the object that currently has focus.

Parameters
eThe Evas canvas to query for focused object on.
Returns
The object that has focus or NULL if there is not one.

Evas can have (at most) one of its objects focused at a time. Focused objects will be the ones having key events delivered to, which the programmer can act upon by means of evas_object_event_callback_add() usage.

Note
Most users wouldn't be dealing directly with Evas' focused objects. Instead, they would be using a higher level library for that (like a toolkit, as Elementary) to handle focus and who's receiving input for them.

This call returns the object that currently has focus on the canvas e or NULL, if none.

See Also
evas_object_focus_set
evas_object_focus_get
evas_object_key_grab
evas_object_key_ungrab

Example:

_object_focus_in_cb, NULL);
{
fprintf(stderr, "ERROR: Callback registering failed! Aborting.\n");
goto panic;
} /* two canvas event callbacks */
d.bg = evas_object_rectangle_add(d.canvas);
evas_object_name_set(d.bg, "our dear rectangle");
evas_object_color_set(d.bg, 255, 255, 255, 255); /* white bg */
evas_object_move(d.bg, 0, 0); /* at canvas' origin */
evas_object_resize(d.bg, WIDTH, HEIGHT); /* covers full canvas */
evas_object_focus_set(d.bg, EINA_TRUE); /* so we get input events */
/* called when our rectangle gets focus */
static void
_object_focus_in_cb(void *data __UNUSED__,
Evas *e,
void *event_info)
{
fprintf(stdout, "An object got focused: %s\n",
evas_object_name_get(event_info));
fprintf(stdout, "Let's recheck it: %s\n",
fprintf(stdout, "And again: %s\n", evas_object_focus_get(event_info) ?
"OK!" : "Oops, something is bad.");
}

In this example the event_info is exactly a pointer to that focused rectangle. See the full example.

Evas_Object* evas_object_bottom_get ( const Evas e)

Get the lowest (stacked) Evas object on the canvas e.

Parameters
ea valid canvas pointer
Returns
a pointer to the lowest object on it, if any, or NULL, otherwise

This function will take all populated layers in the canvas into account, getting the lowest object for the lowest layer, naturally.

See Also
evas_object_layer_get()
evas_object_layer_set()
evas_object_below_get()
evas_object_above_get()
Warning
This function will skip objects parented by smart objects, acting only on the ones at the "top level", with regard to object parenting.
Evas_Object* evas_object_name_child_find ( const Evas_Object obj,
const char *  name,
int  recurse 
)

Retrieves the object from children of the given object with the given name.

Parameters
objThe parent (smart) object whose children to search.
nameThe given name.
recurseSet to the number of child levels to recurse (0 == don't recurse, 1 == only look at the children of obj or their immediate children, but no further etc.).
Returns
If successful, the Evas object with the given name. Otherwise, NULL.

This looks for the evas object given a name by evas_object_name_set(), but it ONLY looks at the children of the object *p obj, and will only recurse into those children if recurse is greater than 0. If the name is not unique within immediate children (or the whole child tree) then it is not defined which child object will be returned. If recurse is set to -1 then it will recurse without limit.

Since
1.2
Evas_Object* evas_object_name_find ( const Evas e,
const char *  name 
)

Retrieves the object on the given evas with the given name.

Parameters
eThe given evas.
nameThe given name.
Returns
If successful, the Evas object with the given name. Otherwise, NULL.

This looks for the evas object given a name by evas_object_name_set(). If the name is not unique canvas-wide, then which one of the many objects with that name is returned is undefined, so only use this if you can ensure the object name is unique.

Evas_Object* evas_object_top_at_pointer_get ( const Evas e)

Retrieve the Evas object stacked at the top at the position of the mouse cursor, over a given canvas.

Parameters
eA handle to the canvas.
Returns
The Evas object that is over all other objects at the mouse pointer's position

This function will traverse all the layers of the given canvas, from top to bottom, querying for objects with areas covering the mouse pointer's position, over e.

Warning
This function will skip objects parented by smart objects, acting only on the ones at the "top level", with regard to object parenting.

References evas_object_top_at_xy_get().

Evas_Object* evas_object_top_at_xy_get ( const Evas e,
Evas_Coord  x,
Evas_Coord  y,
Eina_Bool  include_pass_events_objects,
Eina_Bool  include_hidden_objects 
)

Retrieve the Evas object stacked at the top of a given position in a canvas.

Parameters
eA handle to the canvas.
xThe horizontal coordinate of the position
yThe vertical coordinate of the position
include_pass_events_objectsBoolean flag to include or not objects which pass events in this calculation
include_hidden_objectsBoolean flag to include or not hidden objects in this calculation
Returns
The Evas object that is over all other objects at the given position.

This function will traverse all the layers of the given canvas, from top to bottom, querying for objects with areas covering the given position. The user can remove from from the query objects which are hidden and/or which are set to pass events.

Warning
This function will skip objects parented by smart objects, acting only on the ones at the "top level", with regard to object parenting.

Referenced by evas_object_top_at_pointer_get().

Evas_Object* evas_object_top_get ( const Evas e)

Get the highest (stacked) Evas object on the canvas e.

Parameters
ea valid canvas pointer
Returns
a pointer to the highest object on it, if any, or NULL, otherwise

This function will take all populated layers in the canvas into account, getting the highest object for the highest layer, naturally.

See Also
evas_object_layer_get()
evas_object_layer_set()
evas_object_below_get()
evas_object_above_get()
Warning
This function will skip objects parented by smart objects, acting only on the ones at the "top level", with regard to object parenting.
Evas_Object* evas_object_top_in_rectangle_get ( const Evas e,
Evas_Coord  x,
Evas_Coord  y,
Evas_Coord  w,
Evas_Coord  h,
Eina_Bool  include_pass_events_objects,
Eina_Bool  include_hidden_objects 
)

Retrieve the Evas object stacked at the top of a given rectangular region in a canvas.

Parameters
eA handle to the canvas.
xThe top left corner's horizontal coordinate for the rectangular region
yThe top left corner's vertical coordinate for the rectangular region
wThe width of the rectangular region
hThe height of the rectangular region
include_pass_events_objectsBoolean flag to include or not objects which pass events in this calculation
include_hidden_objectsBoolean flag to include or not hidden objects in this calculation
Returns
The Evas object that is over all other objects at the given rectangular region.

This function will traverse all the layers of the given canvas, from top to bottom, querying for objects with areas overlapping with the given rectangular region inside e. The user can remove from the query objects which are hidden and/or which are set to pass events.

Warning
This function will skip objects parented by smart objects, acting only on the ones at the "top level", with regard to object parenting.
Eina_List* evas_objects_at_xy_get ( const Evas e,
Evas_Coord  x,
Evas_Coord  y,
Eina_Bool  include_pass_events_objects,
Eina_Bool  include_hidden_objects 
)

Retrieve a list of Evas objects lying over a given position in a canvas.

Parameters
eA handle to the canvas.
xThe horizontal coordinate of the position
yThe vertical coordinate of the position
include_pass_events_objectsBoolean flag to include or not objects which pass events in this calculation
include_hidden_objectsBoolean flag to include or not hidden objects in this calculation
Returns
The list of Evas objects that are over the given position in e

This function will traverse all the layers of the given canvas, from top to bottom, querying for objects with areas covering the given position. The user can remove from from the query objects which are hidden and/or which are set to pass events.

Warning
This function will skip objects parented by smart objects, acting only on the ones at the "top level", with regard to object parenting.
Eina_List* evas_objects_in_rectangle_get ( const Evas e,
Evas_Coord  x,
Evas_Coord  y,
Evas_Coord  w,
Evas_Coord  h,
Eina_Bool  include_pass_events_objects,
Eina_Bool  include_hidden_objects 
)

Retrieves the objects in the given rectangle region.

Parameters
eThe given evas object.
xThe horizontal coordinate.
yThe vertical coordinate.
wThe width size.
hThe height size.
include_pass_events_objectsBoolean Flag to include or not pass events objects
include_hidden_objectsBoolean Flag to include or not hidden objects
Returns
The list of evas object in the rectangle region.