Gets the Evas object stacked right above obj.

Since :

2.3.1

Remarks:

This function traverses layers in its search, if there are objects on layers above the one obj is placed at.

Parameters:

[in]

obj

An Evas_Object

Returns:

The Evas_Object directly above obj, if any,
otherwise NULL if none

See also:

evas_object_layer_get()

evas_object_layer_set()

evas_object_below_get()

Gets the Evas object stacked right below obj.

This function traverses layers in its search, if there are objects on layers below the one obj is placed at.

Since :

2.3.1

Parameters:

[in]

obj

An Evas_Object

Returns:

The Evas_Object directly below obj, if any,
otherwise NULL if none

See also:

evas_object_layer_get()

evas_object_layer_set()

evas_object_below_get()

Gets the object clipping obj (if any).

This function returns the object clipping obj. If obj is not being clipped at all, NULL is returned. The object obj must be a valid Evas_Object.

Since :

2.3.1

Remarks:

See also evas_object_clip_set(), evas_object_clip_unset() and evas_object_clipees_get().

Parameters:

[in]

obj

The object to get the clipper from

Returns:

The object clipping obj
If obj object is not being clipped, NULL is returned.

Clips one object to another.

This function clips the object obj to the area occupied by the object clip. This means the object obj is only visible within the area occupied by the clipping object (clip).

Since :

2.3.1

Remarks:

The color of the object being clipped is multiplied by the color of the clipping one, so the resulting color for the former is RESULT = (OBJ * CLIP) / (255 * 255), per color element (red, green, blue and alpha).

Clipping is recursive, so clipping objects may be clipped by others, and their color is in term multiplied. You may not set up circular clipping lists (i.e. object 1 clips object 2, which clips object 1): the behavior of Evas is undefined in this case.

Objects which do not clip others are visible in the canvas as normal; those that clip one or more objects become invisible themselves, only affecting what they clip. If an object ceases to have other objects being clipped by it, it becomes visible again.

The visibility of an object affects the objects that are clipped by it, so if the object clipping others is not shown (as in evas_object_show()), the objects clipped by it is not shown either.

If obj is being clipped by another object when this function is called, it gets implicitly removed from the old clipper's domain and is made now to be clipped by its new clipper.

The following figure illustrates some clipping in Evas:

Remarks:

At the moment the only objects that can validly be used to clip other objects are rectangle objects. All other object types are invalid and the result of using them is undefined. The clip object clip must be a valid object, but can also be NULL, in which case the effect of this function is the same as calling evas_object_clip_unset() on the obj object.

Parameters:

[in]	obj	The object to be clipped
[in]	clip	The object to clip obj by

Disables or ceases clipping on a clipped obj object.

This function disables clipping for the object obj, if it is already clipped, i.e., its visibility and color get detached from the previous clipper. If it is not already clipped, this has no effect. The object obj must be a valid Evas_Object.

Since :

2.3.1

Remarks:

See also evas_object_clip_set() (for an example), evas_object_clipees_get() and evas_object_clip_get().

Parameters:

[in]

obj

The object to cease clipping on

Gets a list of objects currently clipped by obj.

This returns the internal list handle that contains all objects clipped by the object obj. If none are clipped by it, the call returns NULL. This list is only valid until the clip list is changed and should be fetched again with another call to evas_object_clipees_get() if any objects being clipped by this object are unclipped, clipped by a new object, deleted or get the clipper deleted. These operations invalidate the list returned, so it should not be used anymore after that point. Any use of the list after this may have undefined results, possibly leading to crashes. The object obj must be a valid Evas_Object.

Since :

2.3.1

Remarks:

See also evas_object_clip_set(), evas_object_clip_unset() and evas_object_clip_get().

The following is an example:

 extern Evas_Object *obj;
 Evas_Object *clipper;

 clipper = evas_object_clip_get(obj);
 if (clipper)
   {
     Eina_List *clippees, *l;
     Evas_Object *obj_tmp;

     clippees = evas_object_clipees_get(clipper);
     printf("Clipper clips %i objects\n", eina_list_count(clippees));
     EINA_LIST_FOREACH(clippees, l, obj_tmp)
         evas_object_show(obj_tmp);
   }

Parameters:

[in]

obj

The object to get a list of clippees from

Returns:

The list of objects being clipped by obj

Gets the general or main color of the given Evas object.

Since :

2.3.1

Remarks:

Gets the "main" color's RGB component (and alpha channel) values, which range from 0 to 255. For the alpha channel, which defines the object's transparency level, 0 means totally transparent, while 255 means opaque. These color values are premultiplied by the alpha value.

Usually you use this attribute for text and rectangle objects, where the "main" color is their unique one. If set for objects which themselves have colors, like the images one, those colors get modulated by this one.

All newly created Evas rectangles get the default color values of 255 255 255 255 (opaque white).

Use NULL pointers on the components you are not interested in: they are ignored by the function.

Parameters:

[in]	obj	The given Evas object to retrieve color from
[out]	r	The pointer to an integer in which to store the red component of the color
[out]	g	The pointer to an integer in which to store the green component of the color
[out]	b	The pointer to an integer in which to store the blue component of the color
[out]	a	The pointer to an integer in which to store the alpha component of the color

Sets the general or main color of the given Evas object.

Since :

2.3.1

Remarks:

These color values are expected to be premultiplied by a.

Parameters:

[in]	obj	The given Evas object
[in]	r	The red component of the given color
[in]	g	The green component of the given color
[in]	b	The blue component of the given color
[in]	a	The alpha component of the given color

See also:

evas_object_color_get() (for an example)

Marks the given Evas object for deletion (when Evas frees its memory).

This call marks obj for deletion, which takes place whenever it has no more references to it (see evas_object_ref() and evas_object_unref()).

Since :

2.3.1

Remarks:

At actual deletion time, which may or may not be just after this call, EVAS_CALLBACK_DEL and EVAS_CALLBACK_FREE callbacks are called. If the object currently had the focus, its EVAS_CALLBACK_FOCUS_OUT callback is also called.

Parameters:

[in]

obj

The given Evas object

See also:

evas_object_ref()

evas_object_unref()

Gets the Evas canvas that the given object lives on.

This function is most useful at code contexts where you need to operate on the canvas but have only the object pointer.

Since :

2.3.1

Parameters:

[in]

obj

The given Evas object

Returns:

A pointer to the canvas where the object is on

Checks whether an object has the focus.

Since :

2.3.1

Remarks:

If the passed object is the currently focused one, EINA_TRUE is returned. EINA_FALSE is returned, otherwise.

Parameters:

[in]

obj

The object to retrieve focus information from

Returns:

EINA_TRUE if the object has the focus,
otherwise EINA_FALSE

See also:

evas_object_focus_set

evas_object_key_grab

evas_object_key_ungrab

Sets or unsets a given object as the currently focused one on its canvas.

Since :

2.3.1

Remarks:

Changing focus only affects where (key) input events go. There can be only one object focused at any time. If focus is EINA_TRUE, obj is set as the currently focused object and it receives all keyboard events that are not exclusive key grabs on other objects.

Parameters:

[in]	obj	The object to be focused or unfocused
[in]	focus	EINA_TRUE to set it as focused, otherwise EINA_FALSE to take away the focus from it

See also:

evas_object_focus_get

evas_object_key_grab

evas_object_key_ungrab

Gets the position and (rectangular) size of the given Evas object.

Since :

2.3.1

Remarks:

The position is relative to the top left corner of the canvas' viewport.

Use NULL pointers on the geometry components you are not interested in: they are ignored by the function.

Parameters:

[in]	obj	The given Evas object
[out]	x	The pointer to an integer in which to store the X coordinate of the object
[out]	y	The pointer to an integer in which to store the Y coordinate of the object
[out]	w	The pointer to an integer in which to store the width of the object
[out]	h	The pointer to an integer in which to store the height of the object

Makes the given Evas object invisible.

Since :

2.3.1

Remarks:

Hidden objects, besides not being shown at all in your canvas, are not checked for changes on the canvas rendering process. Furthermore, they do not catch input events. Thus, they are much lighter (in processing needs) than an object that is invisible due to indirect causes, such as being clipped or out of the canvas' viewport.

Besides becoming hidden, obj object's EVAS_CALLBACK_SHOW callback is called.

All objects are created in the hidden state. If you want to show them, use evas_object_show() after their creation.

Parameters:

[in]

obj

The given Evas object

See also:

evas_object_show()

evas_object_visible_get()

Gets the layer of its canvas that the given object is part of.

Since :

2.3.1

Parameters:

[in]

obj

The given Evas object to query the layer from

Returns:

The number of its layer

See also:

evas_object_layer_set()

Sets the layer of its canvas that the given object is part of.

Since :

2.3.1

Remarks:

If you do not use this function, you are dealing with a unique layer of objects, the default one. Additional layers are handy when you do not want a set of objects to interfere with another set with regard to stacking. Two layers are completely disjoint in that matter.

This is a low-level function, which you would be using when something should be always on top, for example.

Be careful, it does not make sense to change the layer of the children of smart objects. Smart objects have a layer of their own, which should contain all their children objects.

Parameters:

[in]	obj	The given Evas object
[in]	l	The number of the layer to place the object on This must be between EVAS_LAYER_MIN and EVAS_LAYER_MAX.

See also:

evas_object_layer_get()

Lowers obj to the bottom of its layer.

Since :

2.3.1

Remarks:

obj is, then, the lowest one in the layer it belongs to. Objects on other layers do not get touched.

Parameters:

[in]

obj

The object to lower

See also:

evas_object_stack_above()

evas_object_stack_below()

evas_object_raise()

Moves the given Evas object to the given location inside its canvas' viewport.

Since :

2.3.1

Remarks:

Besides being moved, the object's EVAS_CALLBACK_MOVE callback is called.

Naturally, newly created objects are placed at the canvas' origin: 0, 0.

Parameters:

[in]	obj	The given Evas object
[in]	x	The X position to move the object to, in canvas units
[in]	y	The Y position to move the object to, in canvas units

Gets the name of the given Evas object.

Since :

2.3.1

Parameters:

[in]

obj

The given object

Returns:

The name of the object,
otherwise NULL if no name has been given to it

Sets the name of the given Evas object to the given name.

Since :

2.3.1

Remarks:

There might be occasions where you would like to name your objects.

Parameters:

[in]	obj	The given object
[in]	name	The given name

Raises obj to the top of its layer.

Since :

2.3.1

Remarks:

obj is, then, the highest one in the layer it belongs to. Objects on other layers do not get touched.

Parameters:

[in]

obj

The object to raise

See also:

evas_object_stack_above()

evas_object_stack_below()

evas_object_lower()

Increments object reference count to defer its deletion.

Since (EFL) :

1.1

Since :

2.3.1

Remarks:

This increments the reference count of an object, which if greater than 0 defers deletion by evas_object_del() until all references are released back (counter back to 0). References cannot go below 0 and unreferencing past that results in the reference count being limited to 0. References are limited to 2^32 - 1 for an object. Referencing it more than this results in it being limited to this value.

This is a very simple reference counting mechanism. For instance, Evas is not ready to check for pending references on a canvas deletion, or things like that. This is useful on scenarios where, inside a code block, callbacks exist which would possibly delete an object that you are operating on afterwards. Then, you would evas_object_ref() it on the beginning of the block and evas_object_unref() it on the end. It would then be deleted at this point, if it should be.

The following is an example:

  evas_object_ref(obj);

  // action here...
  evas_object_smart_callback_call(obj, SIG_SELECTED, NULL);
  // more action here...
  evas_object_unref(obj);

Parameters:

[in]

obj

The given Evas object to reference

See also:

evas_object_unref()

evas_object_del()

Gets the object reference count.

This gets the reference count for an object (normally 0 until it is referenced). Values of 1 or greater mean that someone is holding a reference to this object that needs to be unreffed before it can be deleted.

Since (EFL) :

1.2

Since :

2.3.1

Parameters:

[in]

obj

The given Evas object to query

Returns:

The object reference count

See also:

evas_object_ref()

evas_object_unref()

evas_object_del()

Changes the size of the given Evas object.

Since :

2.3.1

Remarks:

Besides being resized, the object's EVAS_CALLBACK_RESIZE callback is called.

Newly created objects have zeroed dimensions. Then, you most probably want to use evas_object_resize() on them after they are created.

Be aware that resizing an object changes its drawing area, but that does imply the object is rescaled. For instance, images are filled inside their drawing area using the specifications of evas_object_image_fill_set(). Thus to scale the image to match exactly your drawing area, you need to change the evas_object_image_fill_set() as well.

This is more evident in images, but text, textblock, lines and polygons behave similarly. Check their specific APIs to know how to achieve your desired behavior. Consider the following example:

 // rescale image to fill exactly its area without tiling:
 evas_object_resize(img, w, h);
 evas_object_image_fill_set(img, 0, 0, w, h);

Parameters:

[in]	obj	The given Evas object
[in]	w	The new width of the Evas object
[in]	h	The new height of the Evas object

Makes the given Evas object visible.

Since :

2.3.1

Remarks:

Besides becoming visible, the object's EVAS_CALLBACK_SHOW callback are called.

Parameters:

[in]

obj

The given Evas object

See also:

evas_object_hide() for more on object visibility.

evas_object_visible_get()

Stacks obj immediately above above.

Since :

2.3.1

Remarks:

Objects, in a given canvas, are stacked in the order they get added to it. This means that, if they overlap, the highest ones cover the lowest ones, in that order. This function is a way to change the stacking order for the objects.

This function is intended to be used with objects belonging to the same layer in a given canvas, otherwise it fails (and accomplish nothing).

If you have smart objects on your canvas and obj is a member of one of them, then above must also be a member of the same smart object.

Similarly, if obj is not a member of a smart object, above must not be either.

Parameters:

[in]	obj	The object to stack
[in]	above	The object above which to stack

See also:

evas_object_layer_get()

evas_object_layer_set()

evas_object_stack_below()

Stacks obj immediately below below.

Since :

2.3.1

Remarks:

Objects, in a given canvas, are stacked in the order they get added to it. This means that, if they overlap, the highest ones cover the lowest ones, in that order. This function is a way to change the stacking order for the objects.

This function is intended to be used with objects belonging to the same layer in a given canvas, otherwise it fails (and accomplish nothing).

If you have smart objects on your canvas and obj is a member of one of them, then below must also be a member of the same smart object.

Similarly, if obj is not a member of a smart object, below must not be either.

Parameters:

[in]	obj	The object to stack
[in]	below	The object below which to stack

See also:

evas_object_layer_get()

evas_object_layer_set()

evas_object_stack_below()

Gets the type of the given Evas object.

Since :

2.3.1

Remarks:

For Evas' built-in types, the return strings are one of:

• "rectangle",
• "line",
• "polygon",
• "text",
• "textblock" and
• "image".

Parameters:

[in]

obj

The given object

Returns:

The type of the object

Decrements object reference count.

This decrements the reference count of an object. If the object has had evas_object_del() called on it while references were more than 0, it is deleted at the time this function is called and puts the counter back to 0. See evas_object_ref() for more information.

Since (EFL) :

1.1

Since :

2.3.1

Parameters:

[in]

obj

The given Evas object to unreference

See also:

evas_object_ref() (for an example)

evas_object_del()

Checks whether the given Evas object is visible.

Since :

2.3.1

This retrieves an object's visibility as the one enforced by evas_object_show() and evas_object_hide().

Remarks:

The value returned is not, by any means, influenced by clippers covering obj, it being out of its canvas' viewport or stacked below other object.

Parameters:

[in]

obj

The given Evas object

Returns:

EINA_TRUE if the object is visible,
otherwise EINA_FALSE if the object is not visible

See also:

evas_object_show()

evas_object_hide() (for an example)