~~Title: Evas Object~~
{{page>index}}
-----
===== Evas Object =====

An Evas object is the most basic visual entity used in Evas. Everything, be it
a single line or a complex list of widgets, is an Evas object.

  * [[#Primitive_Renderable_Objects|Primitive Renderable Objects]]
    * [[#Rectangle|Rectangle]] ([[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Evas__Object__Rectangle.html|API]]).
    * [[#Text|Text]] ([[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Evas__Object__Text.html| API]]).
    * [[/develop/legacy/program_guide/evas/textblock_objects|Textblock]] ([[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Evas__Object__Textblock.html|API]])
    * [[/develop/legacy/program_guide/evas/image_objects|Image]] ([[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Evas__Object__Image.html|API]])
  * [[#Primitive_Smart_Objects|Primitive Smart Objects]] ([[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Evas__Smart__Object__Group.html|API]])
    * [[#Primitive_Container_Objects|Primitive Container Objects]]
      * [[#Table|Table]] ([[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Evas__Object__Table.html|API]])
      * [[#Grid|Grid]] ([[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Evas__Object__Grid.html|API]])
      * [[#Box|Box]] ([[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Evas__Object__Box.html|API]])

==== Primitive Renderable Objects ====

Primitive objects are the base upon which to build a complex interface:
rectangles, lines, polygons, [[/develop/legacy/program_guide/evas/image_objects|images]],
[[/develop/legacy/program_guide/evas/textblock_objects|textblocks]] and texts.

=== Rectangle ===

There is only one function to deal with rectangle objects (see
[[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Evas__Object__Rectangle.html|Rectangle
Object Functions API]]). However, the rectangle is manipulated using the
generic evas object functions.

The evas rectangle serves a number of key functions when working on Evas
programs.

   * background
   * debugging
   * clipper

== Background ==

A common requirement of Evas programs is to have a solid color background,
which can be accomplished with the following code.

<code c>
Evas_Object *bg = evas_object_rectangle_add(evas_canvas);

//Here we set the rectangles red, green, blue and opacity levels
evas_object_color_set(bg, 255, 255, 255, 255); // opaque white background
evas_object_resize(bg, WIDTH, HEIGHT); // covers full canvas
evas_object_show(bg);
</code>

== Debugging ==

When debugging visual issues with evas programs, the rectangle is a useful
tool. The rectangle's simplicity means that it is easier to pinpoint issues
with it than with more complex objects. A common technique to use when writing
an evas program and not getting the desired visual result is to replace an
object for a solid color rectangle and seeing how it interacts with the other
elements. This often allows us to notice clipping, parenting or positioning
issues. Once the issues are identified and corrected, the rectangle can be
replaced for the original object, and in all likelihood any remaining issues
are specific to that object's type.

== Clipping ==

[[/develop/legacy/program_guide/evas/clippling_objects|Clipping]] serves two main functions:

   * limiting visibility
   * applying a layer of color to an object

=== Text ===

An Evas text object shows a basic single-line single-style text (see
[[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Evas__Object__Text.html|
Text Object Functions API]]).

<code c>
Evas_Object *text = evas_object_text_add(evas_canvas);
evas_object_text_text_set(text, "some text");
evas_object_color_set(text, 127, 0, 0, 127);
evas_object_show(text);
</code>

To set the text, use ''evas_object_text_text_set(text, some_text)''. You can
set the current text with ''evas_object_text_text_get(text)''.

To set the font, use ''evas_object_text_font_set(text, font, size)'':

   * ''text'': The text object
   * ''font'': The font name you want to use
   * ''size'': The font size you want to use. To query the current font, use ''evas_object_text_font_set(text, font, size)''.

To set the text style, use ''evas_object_text_style_set(text, style)''. The
following styles are supported:

   * ''EVAS_TEXT_STYLE_PLAIN'': Plain, standard text
   * ''EVAS_TEXT_STYLE_SHADOW'': Text with shadow underneath
   * ''EVAS_TEXT_STYLE_OUTLINE'': Text with an outline
   * ''EVAS_TEXT_STYLE_SOFT_OUTLINE'': Text with a soft outline
   * ''EVAS_TEXT_STYLE_GLOW'': Text with a glow effect
   * ''EVAS_TEXT_STYLE_OUTLINE_SHADOW'': Text with both outline and shadow effects
   * ''EVAS_TEXT_STYLE_FAR_SHADOW'': Text with (far) shadow underneath
   * ''EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW'': Text with outline and soft shadow effects combined
   * ''EVAS_TEXT_STYLE_SOFT_SHADOW'': Text with (soft) shadow underneath
   * ''EVAS_TEXT_STYLE_FAR_SOFT_SHADOW'': Text with (far soft) shadow underneath
   * ''EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_RIGHT'': Shadow growing to bottom right
   * ''EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM'': Shadow growing to the bottom
   * ''EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_LEFT'': Shadow growing to bottom left
   * ''EVAS_TEXT_STYLE_SHADOW_DIRECTION_LEFT'': Shadow growing to the left
   * ''EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_LEFT'': Shadow growing to top left
   * ''EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP'': Shadow growing to the top
   * ''EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_RIGHT'': Shadow growing to top right
   * ''EVAS_TEXT_STYLE_SHADOW_DIRECTION_RIGHT'': Shadow growing to the right. To query the current style, use ''evas_object_text_style_get(text)''.


If the text does not fit, make an ellipsis on it by using
''evas_object_text_ellipsis_set(text, ellipsis)''. The (float) value
specifies, which part of the text is shown.

   * ''0.0'': The beginning is shown and the end trimmed.
   * ''1.0'': The beginning is trimmed and the end shown.
   * Any value in between means that both ends of the text have ellipsis and the set part is shown.
   * ''-1.0'': Ellipsis is disabled. To query the current ellipsis value, use ''evas_object_text_ellipsis_get(text)''.

When the text style is set to glow, set the glow color using
''evas_object_text_glow_color_set(text, r, g, b, a)'', where ''r'', ''g'',
''b'', and ''a'' are respectively the red, green, blue, and alpha values. The
effect is placed at a short distance from the text but not touching it. For
glows set right at the text, use ''evas_object_text_glow2_color_set(text, r,
g, b, a)''. To query the current color, use
''evas_object_text_glow_color_get(text, r, g, b, a)'', respectively
''evas_object_text_glow2_color_get(text, r, g, b, a)''.

If your text style is set to display a shadow, use
''evas_object_text_shadow_color_set(text, r, g, b, a)'', where ''r'', ''g'',
''b'', and ''a'' are respectively the red, green, blue, and alpha values. To
query the current color, use ''evas_object_text_shadow_color_get(text, r, g,
b, a)''

If your text style is set to display an outline, use
''evas_object_text_outline_color_set(text, r, g, b, a)'', where ''r'', ''g'',
''b'', and ''a'' are respectively the red, green, blue, and alpha values. To
query the current color, use ''evas_object_text_outline_color_get(text, r, g,
b, a)''

=== Textblock ===

See [[/develop/legacy/program_guide/evas/textblock_objects|Textblock]] section.

=== Image ===

See [[/develop/legacy/program_guide/evas/image_objects|Image]] section.

==== Primitive Smart Objects ====

A smart object is a special Evas object that provides custom functions to
handle automatically clipping, hiding, moving, resizing color setting and more
on child elements, for the smart object's user. They could be, for example, a
group of objects that move together, or implementations of whole complex UI
widgets, providing some intelligence and extension to simple Evas objects.

  * [[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Evas__Smart__Object__Group.html|Smart Object Functions API]]

=== Primitive Container Objects ===

A container is a Smart object that holds children Evas objects in a specific
fashion.

== Table ==

A table is a smart object that packs children using a tabular layout (see
[[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Evas__Object__Table.html|Table
Smart Object API]]).

<code c>
table = evas_object_table_add(evas);
evas_object_table_homogeneous_set(table, EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE);
evas_object_table_padding_set(table, 0, 0);
evas_object_resize(table, WIDTH, HEIGHT);
evas_object_show(table);

rect = evas_object_rectangle_add(evas);
evas_object_color_set(rect, 255, 0, 0, 255);
evas_object_size_hint_min_set(rect, 100, 50);
evas_object_show(rect);
evas_object_table_pack(table, rect, 1, 1, 2, 1);

rect = evas_object_rectangle_add(d.evas);
evas_object_color_set(rect, 0, 255, 0, 255);
evas_object_size_hint_min_set(rect, 50, 100);
evas_object_show(rect);
evas_object_table_pack(table, rect, 1, 2, 1, 2);

rect = evas_object_rectangle_add(d.evas);
evas_object_color_set(rect, 0, 0, 255, 255);
evas_object_size_hint_min_set(rect, 50, 50);
evas_object_show(rect);
evas_object_table_pack(table, rect, 2, 2, 1, 1);

rect = evas_object_rectangle_add(d.evas);
evas_object_color_set(rect, 255, 255, 0, 255);
evas_object_size_hint_min_set(rect, 50, 50);
evas_object_show(rect);
evas_object_table_pack(table, rect, 2, 3, 1, 1);
</code>

In this example, we add a non-homogeneous table to the canvas with its padding
set to 0.

We then add four different colored rectangles with different properties.

   * the first one, at the first column and first line, spans two columns and one line
   * the second one, at the first column and second line, spans one columns and two lines
   * the third one, at the second column and second line, fits in one cell
   * the fourth one, at the second column and third line, also fits in one cell


To create a table, use ''evas_object_table_add(evas)''.

To set the table layout (the cells), use
''evas_object_table_homogeneous_set(table, homogeneous)''. The following
values can be homogeneous:

   * ''EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE'': This default value has columns and rows calculated based on hints of individual cells. This is flexible, but much heavier on computations.
   * ''EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE'': The table size is divided equally among children, filling the whole table area. If the children have a minimum size that is larger than this (including padding), then the table overflows and is aligned respecting the alignment hint, possibly overlapping sibling cells.
   * ''EVAS_OBJECT_TABLE_HOMOGENEOUS_ITEM'': The greatest minimum cell size is used: if no element is set to expand, the contents of the table are the minimum size and the bounding box of all the children is aligned relatively to the table object using ''evas_object_table_align_get()''. If the table area is too small to hold this minimum bounding box, then the objects keep their size and the bounding box overflows the box area, still respecting the alignment. To set the current mode, use ''evas_object_table_homogeneous_get(table)''.


The table's content alignment is set using
''evas_object_table_align_set(table, horizontal, vertical)'', where
''horizontal'' and ''vertical'' are floating values. To see them, use
''evas_object_table_align_get(table, horizontal, vertical)''.

To set the padding, use ''evas_object_table_padding_set(table, horizontal,
vertical)''. To see the current value, use
''evas_object_table_padding_get(table, horizontal, vertical)''.

To see the current column and row count, use
''evas_object_table_col_row_size_get(table, columns, rows)''.

== Grid ==

A grid is a smart object that packs its children as with a regular grid layout
(see
[[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Evas__Object__Grid.html|Grid
Smart Object API]])

Grids are added to the canvas with ''evas_object_grid_add(evas)''.

To change a grid's virtual resolution, use ''evas_object_grid_size_set(grid,
width, height)'', to see it, use ''evas_object_grid_size_get(grid, width,
height)''.

To add an object, use ''evas_object_grid_pack(grid, child, x, y, w, h)'',
where

   * ''x'' is the virtual X coordinate of the child
   * ''y'' is the virtual y coordinate of the child
   * ''w'' is the virtual width of the child
   * ''h'' is the virtual height of the child

== Box ==

A box is a simple container that sets its children objects linearly (see
[[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Evas__Object__Box.html|Box
Smart Object API]]).

To add a box to your canvas, use ''evas_object_box_add(evas)''.

To add a child to the box, use

   * ''evas_object_box_append(box, child)'': The child is appended.
   * ''evas_object_box_insert_after(box, child, reference)'': The child is added after ''reference''.
   * ''evas_object_box_insert_before(box, child, reference)'': The child is added before ''reference''.
   * ''evas_object_box_insert_at(box, child, pos)'': The child is added at the specified position.

To set the alignment, use ''evas_object_box_align_set(box, horizontal,
vertical)''.

   * ''horizontal'': 0.0 means aligned to the left, 1.0 means to the right;
   * ''vertical'': 0.0 means aligned to the top, 1.0 means to the bottom.

Evas has predefined box layouts available:

   * ''evas_object_box_layout_horizontal()'';
   * ''evas_object_box_layout_vertical()'';
   * ''evas_object_box_layout_homogeneous_horizontal()'';
   * ''evas_object_box_layout_homogeneous_vertical()'';
   * ''evas_object_box_layout_homogeneous_max_size_horizontal()'';
   * ''evas_object_box_layout_homogeneous_max_size_vertical()'';
   * ''evas_object_box_layout_flow_horizontal()'';
   * ''evas_object_box_layout_flow_vertical()'';
   * ''evas_object_box_layout_stack()''.

\\
-----
{{page>index}}