Functions
Basic Object Manipulation

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

Functions

void evas_vg_node_color_set (Eo *obj, int r, int g, int b, int a)
 Sets the general/main color of the given Efl_Vg object to the given one. More...
 
void evas_object_ref (Evas_Object *obj)
 Increments object reference count to defer its deletion. More...
 
void evas_object_unref (Evas_Object *obj)
 Decrements object reference count. More...
 
int evas_object_ref_get (const Evas_Object *obj)
 Get the object reference count. More...
 
void evas_object_del (Evas_Object *obj)
 Marks the given Evas object for deletion (when Evas will free its memory). More...
 
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. More...
 
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. More...
 
void evas_object_show (Evas_Object *obj)
 Makes the given Evas object visible. More...
 
void evas_object_hide (Evas_Object *obj)
 Makes the given Evas object invisible. More...
 
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. More...
 
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. More...
 

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:

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

Function Documentation

void evas_object_ref ( Evas_Object obj)

Increments object reference count to defer its deletion.

Parameters
objThe 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:

1 evas_object_ref(obj);
2 
3 // action here...
4 evas_object_smart_callback_call(obj, SIG_SELECTED, NULL);
5 // more action here...
6 evas_object_unref(obj);
Since
1.1

References eo_data_scope_get(), and eo_ref().

void evas_object_unref ( Evas_Object obj)

Decrements object reference count.

Parameters
objThe 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 eo_data_scope_get(), eo_unref(), and evas_object_del().

int evas_object_ref_get ( const Evas_Object obj)

Get the object reference count.

Parameters
objThe 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

References eo_data_scope_get().

void evas_object_del ( Evas_Object obj)

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

Parameters
objThe 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_COW_WRITE_BEGIN, EINA_COW_WRITE_END, EINA_FALSE, eina_list_count(), eina_list_data_get(), EINA_LIST_FOREACH_SAFE, EINA_LIST_FREE, eina_list_remove(), EINA_TRUE, eo_data_scope_get(), eo_del(), eo_isa(), eo_manual_free_set(), ERR, EVAS_CALLBACK_DEL, EVAS_CALLBACK_FOCUS_OUT, EVAS_CALLBACK_FREE, evas_canvas3d_texture_source_set(), evas_object_hide(), and evas_object_image_source_unset().

Referenced by ecore_evas_ews_background_set(), ecore_evas_pixmap_depth_get(), edje_box_layout_register(), edje_edit_object_add(), edje_edit_part_source_get(), edje_edit_part_source_set(), edje_edit_sound_tones_list_get(), edje_edit_source_generate(), edje_evas_global_perspective_get(), edje_file_data_get(), edje_perspective_free(), edje_shutdown(), emotion_object_file_get(), emotion_object_suspend_get(), ethumb_file_free(), ethumb_free(), ethumb_new(), evas_object_box_smart_class_get(), evas_object_grid_add(), evas_object_smart_add(), evas_object_table_add(), evas_object_unref(), and evas_smart_legacy_type_register().

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
objThe given Evas object.
xPointer to an integer in which to store the X coordinate of the object.
yPointer to an integer in which to store the Y coordinate of the object.
wPointer to an integer in which to store the width of the object.
hPointer 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:

1  int w, h, cw, ch;
2 
3  evas_object_geometry_get(d.img, NULL, NULL, &w, &h);
4  ecore_evas_geometry_get(d.ee, NULL, NULL, &cw, &ch);
5 
6  if (w < cw)
7  evas_object_resize(d.img, cw, ch);
8  else
9  evas_object_resize(d.img, cw / 2, ch / 2);
10 
11  return EINA_TRUE; /* re-issue the timer */

See the full example.

Referenced by edje_evas_global_perspective_get(), emotion_object_border_set(), emotion_object_file_get(), emotion_object_keep_aspect_set(), emotion_object_suspend_get(), evas_object_box_smart_class_get(), evas_object_image_alpha_mask_set(), evas_object_image_source_unset(), evas_object_top_at_pointer_get(), and evas_textblock_cursor_range_simple_geometry_get().

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
objThe given Evas object.
xX position to move the object to, in canvas units.
yY position to move the object to, in canvas units.
wThe new width of the Evas object.
hThe 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
void evas_object_show ( Evas_Object obj)

Makes the given Evas object visible.

Parameters
objThe 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()

Referenced by ecore_evas_ews_background_set(), ecore_evas_pixmap_depth_get(), edje_edit_part_name_set(), edje_file_data_get(), edje_transition_duration_factor_set(), emotion_object_bg_color_set(), emotion_object_file_get(), emotion_object_suspend_get(), and ethumb_file_free().

void evas_object_hide ( Evas_Object obj)

Makes the given Evas object invisible.

Parameters
objThe 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:

1  if (evas_object_visible_get(d.clipper))
2  {
3  evas_object_hide(d.clipper);
4  fprintf(stdout, "hidden\n");
5  }
6  else
7  {
8  evas_object_show(d.clipper);
9  fprintf(stdout, "visible\n");
10  }
11  return;

See the full example.

Referenced by ecore_evas_cursor_unset(), edje_edit_part_del(), edje_transition_duration_factor_set(), emotion_object_bg_color_set(), emotion_object_suspend_get(), ethumb_file_free(), and evas_object_del().

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]rThe red component of the given color.
[in]gThe green component of the given color.
[in]bThe blue component of the given color.
[in]aThe alpha component of the given color.

References EINA_FALSE, EINA_TRUE, and ERR.

Referenced by ecore_evas_ews_background_set(), edje_edit_part_name_set(), edje_file_data_get(), emotion_object_bg_color_set(), emotion_object_file_get(), and emotion_object_suspend_get().

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:

1  int alpha, r, g, b;
2 
3  evas_object_color_get(d.clipper, &r, &g, &b, &alpha);
4  evas_color_argb_unpremul(alpha, &r, &g, &b);
5 
6  alpha -= 20;
7  if (alpha < 0)
8  alpha = 255;
9 
10  evas_color_argb_premul(alpha, &r, &g, &b);
11  evas_object_color_set(d.clipper, r, g, b, alpha);
12 
13  fprintf(stdout, "Changing clipper's opacity: %d%%\n",
14  (int)((alpha / 255.0) * 100));
15  return;

See the full example.

Parameters
[out]rThe red component of the given color.
[out]gThe green component of the given color.
[out]bThe blue component of the given color.
[out]aThe alpha component of the given color.

References EINA_FALSE, EINA_INLIST_GET, EINA_INLIST_REVERSE_FOREACH, EINA_TRUE, EINA_VALUE_TYPE_CHAR, EINA_VALUE_TYPE_DOUBLE, EINA_VALUE_TYPE_INT, EINA_VALUE_TYPE_STRING, EINA_VALUE_TYPE_UINT64, EO_DBG_INFO_APPEND, EO_DBG_INFO_LIST_APPEND(), evas_map_count_get(), evas_map_point_coord_get(), evas_map_point_image_uv_get(), EVAS_OBJECT_POINTER_MODE_NOGRAB, and EVAS_OBJECT_POINTER_MODE_NOGRAB_NO_REPEAT_UPDOWN.

Referenced by emotion_object_bg_color_get(), and emotion_object_suspend_get().

void evas_vg_node_color_set ( Eo obj,
int  r,
int  g,
int  b,
int  a 
)

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

See also
evas_vg_node_color_get() (for an example)
Note
These color values are expected to be premultiplied by a.
Parameters
[in]rThe red component of the given color.
[in]gThe green component of the given color.
[in]bThe blue component of the given color.
[in]aThe alpha component of the given color.