Basic Object Manipulation
Evas » Generic Object Functions

Almost every evas object created will have some generic function used to manipulate it. More...

EVAS_API void | evas_object_ref (Evas_Object *obj)
| Increments object reference count to defer its deletion.
EVAS_API void | evas_object_unref (Evas_Object *obj)
| Decrements object reference count.
EVAS_API int | evas_object_ref_get (const Evas_Object *obj)
| Get the object reference count.
EVAS_API void | evas_object_del (Evas_Object *obj)
| Marks the given Evas object for deletion (when Evas will free its memory).
EVAS_API const char * | evas_object_type_get (const Evas_Object *obj)
| Retrieves the type of the given Evas object.
EVAS_API void | evas_object_name_set (Evas_Object *obj, const char *name)
| Sets the name of the given Evas object to the given name.
EVAS_API const char * | evas_object_name_get (const Evas_Object *obj)
| Retrieves the name of the given Evas object.
EVAS_API 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.
EVAS_API void | evas_object_geometry_get (const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h)
| Retrieves the position and (rectangular) size of the given Evas object.
EVAS_API void | evas_object_geometry_set (Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h)
| Set the position and (rectangular) size of the given Evas object.
EVAS_API void | evas_object_show (Evas_Object *obj)
| Makes the given Evas object visible.
EVAS_API void | evas_object_hide (Evas_Object *obj)
| Makes the given Evas object invisible.
EVAS_API void | evas_object_color_set (Evas_Object *obj, int r, int g, int b, int a)
| Sets the general/main color of the given Evas object to the given one.
EVAS_API void | evas_object_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a)
| Retrieves the general/main color of the given Evas object.

## Detailed Description

Almost every evas object created will have some generic function used to manipulate it.

That's because there are a number of basic actions to be done to objects that are irrespective of the object's type, things like:

- Showing/Hiding
- Setting (and getting) geometry
- Bring up or down a layer
- Color management
- Handling focus
- Clipping
- Reference counting

All of these issues are handled through the functions grouped here. Examples of these function can be seen in Example_Evas_Object_Manipulation(which deals with the most common ones) and in Evas object stacking functions (and some event handling) (which deals with stacking functions).

## Function Documentation

## evas_object_ref()

EVAS_API void evas_object_ref | ( | Evas_Object * | obj | ) |

Increments object reference count to defer its deletion.

Parameters

  obj | The given Evas object to reference

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

See also
  evas_object_unref()
  evas_object_del()

Note
  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 we are operating on afterwards. Then, one 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.

Example:

evas_object_ref(obj);
// action here...
evas_object_smart_callback_call(obj, SIG_SELECTED, NULL);
// more action here...
evas_object_unref(obj);
evas_object_unref
EVAS_API void evas_object_unref(Evas_Object *eo_obj)
Decrements object reference count.
Definition evas_object_main.c:899
evas_object_ref
EVAS_API void evas_object_ref(Evas_Object *eo_obj)
Increments object reference count to defer its deletion.
Definition evas_object_main.c:885
evas_object_smart_callback_call
EVAS_API void evas_object_smart_callback_call(Evas_Object *eo_obj, const char *event, void *event_info)
Call a given smart callback on the smart object obj.
Definition evas_object_smart.c:1151

Since
  1.1

## evas_object_unref()

EVAS_API void evas_object_unref | ( | Evas_Object * | obj | ) |

Decrements object reference count.

Parameters

  obj | The given Evas object to unreference

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 will be deleted at the time this function is called and puts the counter back to 0. See evas_object_ref() for more information.

See also
  evas_object_ref() (for an example)
  evas_object_del()

Since
  1.1

References evas_object_del().

## evas_object_ref_get()

EVAS_API int evas_object_ref_get | ( | const Evas_Object * | obj | ) |

Get the object reference count.

Parameters

  obj | The given Evas object to query

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.

See also
  evas_object_ref()
  evas_object_unref()
  evas_object_del()

Since
  1.2

## evas_object_del()

EVAS_API void evas_object_del | ( | Evas_Object * | obj | ) |

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

Parameters

  obj | The given Evas object.

This call will mark `obj` for deletion, which will take place whenever it has no more references to it (see evas_object_ref() and evas_object_unref()).

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

See also
  evas_object_ref()
  evas_object_unref()

References EINA_TRUE, and ERR.

Referenced by edje_edit_part_source_set(), edje_perspective_free(), elm_code_free(), elm_object_cursor_unset(), elm_quicklaunch_seed(), ethumb_free(), and evas_object_unref().

## evas_object_type_get()

EVAS_API const char * evas_object_type_get | ( | const Evas_Object * | obj | ) |

Retrieves the type of the given Evas object.

For Evas' builtin types, the return strings will be one of "rectangle", "line", "polygon", "text", "textblock" or "image".

For Evas smart objects (see Smart Functions), the name of the smart class itself is returned on this call. For the built-in smart objects, these names are "EvasObjectSmartClipped" for the clipped smart object, "Evas_Object_Box" for the box object and "Evas_Object_Table for the table object.

Returns
  The type of the object.

Since
  1.18

## evas_object_name_set()

EVAS_API void evas_object_name_set | ( | Evas_Object * | obj,
|  | const char * | name )

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

There might be occasions where one would like to name his/her objects.

Parameters

  [in] | name | The given name.

References eina_hash_list_prepend(), and eina_hash_list_remove().

Referenced by edje_perspective_global_set().

## evas_object_name_get()

EVAS_API const char * evas_object_name_get | ( | const Evas_Object * | obj | ) |

Retrieves the name of the given Evas object.

Return: The name of the object or `null`, if no name has been given to it.

Returns
  The given name.

## evas_object_name_child_find()

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

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.

Parameters

  [in] | name | The given name.
  [in] | recurse | Set 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
  The Evas object with the given name on success, Otherwise `null`.

Since
  1.2

## evas_object_geometry_get()

EVAS_API void evas_object_geometry_get | ( | const Evas_Object * | obj,
|  | Evas_Coord * | x,
|  | Evas_Coord * | y,
|  | Evas_Coord * | w,
|  | Evas_Coord * | h )

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

Parameters

  obj | The given Evas object.
  x | Pointer to an integer in which to store the X coordinate of the object.
  y | Pointer to an integer in which to store the Y coordinate of the object.
  w | Pointer to an integer in which to store the width of the object.
  h | Pointer to an integer in which to store the height of the object.

The position, naturally, will be relative to the top left corner of the canvas' viewport.

Note
  Use `NULL` pointers on the geometry components you're not interested in: they'll be ignored by the function.

Example:

int w, h, cw, ch;
evas_object_geometry_get(d.img, NULL, NULL, &w, &h);
ecore_evas_geometry_get(d.ee, NULL, NULL, &cw, &ch);
if (w < cw)
evas_object_resize(d.img, cw, ch);
else
evas_object_resize(d.img, cw / 2, ch / 2);
return EINA_TRUE; /* re-issue the timer */
ecore_evas_geometry_get
EAPI void ecore_evas_geometry_get(const Ecore_Evas *ee, int *x, int *y, int *w, int *h)
Gets the geometry of an Ecore_Evas.
Definition ecore_evas.c:1376
EINA_TRUE
#define EINA_TRUE
boolean value TRUE (numerical value 1)
Definition eina_types.h:539
evas_object_geometry_get
EVAS_API void evas_object_geometry_get(const Evas_Object *eo_obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h)
Retrieves the position and (rectangular) size of the given Evas object.
Definition evas_object_main.c:1335
evas_object_resize
EVAS_API void evas_object_resize(Evas_Object *obj, Evas_Coord w, Evas_Coord h)
Changes the size of the given Evas object.
Definition evas_object_main.c:1236

See the full example.

Referenced by elm_drag_start(), emotion_object_border_set(), emotion_object_keep_aspect_set(), and evas_textblock_cursor_range_simple_geometry_get().

## evas_object_geometry_set()

EVAS_API void evas_object_geometry_set | ( | Evas_Object * | obj,
|  | Evas_Coord | x,
|  | Evas_Coord | y,
|  | Evas_Coord | w,
|  | Evas_Coord | h )

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

Parameters

  obj | The given Evas object.
  x | X position to move the object to, in canvas units.
  y | Y position to move the object to, in canvas units.
  w | The new width of the Evas object.
  h | The new height of the Evas object.

The position, naturally, will be relative to the top left corner of the canvas' viewport.

If the object get moved, the object's EVAS_CALLBACK_MOVE callback will be called.

If the object get resized, the object's EVAS_CALLBACK_RESIZE callback will be called.

See also
  evas_object_move()
  evas_object_resize()
  evas_object_geometry_get

Since
  1.8

References EINA_RECT.

## evas_object_show()

EVAS_API void evas_object_show | ( | Evas_Object * | obj | ) |

Makes the given Evas object visible.

Parameters

  obj | The given Evas object.

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

See also
  evas_object_hide() for more on object visibility.
  evas_object_visible_get()

References EINA_TRUE.

Referenced by elm_drag_start(), elm_image_preload_disabled_set(), and elm_quicklaunch_seed().

## evas_object_hide()

EVAS_API void evas_object_hide | ( | Evas_Object * | obj | ) |

Makes the given Evas object invisible.

Parameters

  obj | The given Evas object.

Hidden objects, besides not being shown at all in your canvas, won't be checked for changes on the canvas rendering process. Furthermore, they will not catch input events. Thus, they are much ligher (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 will be called.

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

See also
  evas_object_show()
  evas_object_visible_get()

Example:

if (evas_object_visible_get(d.clipper))
{
evas_object_hide(d.clipper);
printf("hidden\n");
}
else
{
evas_object_show(d.clipper);
printf("visible\n");
}
return;
evas_object_show
EVAS_API void evas_object_show(Evas_Object *eo_obj)
Makes the given Evas object visible.
Definition evas_object_main.c:1814
evas_object_hide
EVAS_API void evas_object_hide(Evas_Object *eo_obj)
Makes the given Evas object invisible.
Definition evas_object_main.c:1823
evas_object_visible_get
EVAS_API Eina_Bool evas_object_visible_get(const Evas_Object *obj)
Retrieves whether or not the given Evas object is visible.
Definition evas_object_main.c:1830

See the full example.

References EINA_FALSE.

Referenced by ecore_evas_cursor_device_unset(), edje_edit_part_del(), and elm_code_free().

## evas_object_color_set()

EVAS_API void evas_object_color_set | ( | Evas_Object * | obj,
|  | int | r,
|  | int | g,
|  | int | b,
|  | int | a )

Sets the general/main color of the given Evas object to the given one.

See also
  evas_object_color_get() (for an example)

Note
  These color values are expected to be premultiplied by `a`.

Parameters

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

Referenced by emotion_object_bg_color_set().

## evas_object_color_get()

EVAS_API void evas_object_color_get | ( | const Evas_Object * | obj,
|  | int * | r,
|  | int * | g,
|  | int * | b,
|  | int * | a )

Retrieves the general/main color of the given Evas object.

Retrieves 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’ll 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.

Note
  All newly created Evas rectangles get the default color values of `255 255 255 255` (opaque white).
  Use `NULL` pointers on the components you're not interested in: they'll be ignored by the function.

Example:

int alpha, r, g, b;
evas_object_color_get(d.clipper, &r, &g, &b, &alpha);
evas_color_argb_unpremul(alpha, &r, &g, &b);
alpha -= 20;
if (alpha < 0)
alpha = 255;
evas_color_argb_premul(alpha, &r, &g, &b);
evas_object_color_set(d.clipper, r, g, b, alpha);
printf("Changing clipper's opacity: %d%%\n",
(int)((alpha / 255.0) * 100));
return;
evas_object_color_set
EVAS_API void evas_object_color_set(Evas_Object *obj, int r, int g, int b, int a)
Sets the general/main color of the given Evas object to the given one.
Definition evas_object_main.c:2024
evas_object_color_get
EVAS_API void evas_object_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a)
Retrieves the general/main color of the given Evas object.
Definition evas_object_main.c:2071
evas_color_argb_unpremul
EVAS_API void evas_color_argb_unpremul(int a, int *r, int *g, int *b)
Undo pre-multiplication of a rgb triplet by an alpha factor.
Definition evas_main.c:1016
evas_color_argb_premul
EVAS_API void evas_color_argb_premul(int a, int *r, int *g, int *b)
Pre-multiplies a rgb triplet by an alpha factor.
Definition evas_main.c:1010

See the full example.

Parameters

  [out] | r | The red component of the given color.
  [out] | g | The green component of the given color.
  [out] | b | The blue component of the given color.
  [out] | a | The alpha component of the given color.

Referenced by emotion_object_bg_color_get().