diff --git a/media/evas_blur1.png b/media/evas_blur1.png new file mode 100644 index 000000000..79de1bf39 Binary files /dev/null and b/media/evas_blur1.png differ diff --git a/media/evas_blur2.png b/media/evas_blur2.png new file mode 100644 index 000000000..794b6144e Binary files /dev/null and b/media/evas_blur2.png differ diff --git a/media/evas_image_loader.png b/media/evas_image_loader.png new file mode 100644 index 000000000..b242092c5 Binary files /dev/null and b/media/evas_image_loader.png differ diff --git a/media/evas_image_scaling.png b/media/evas_image_scaling.png new file mode 100644 index 000000000..2b8c4d086 Binary files /dev/null and b/media/evas_image_scaling.png differ diff --git a/media/evas_immediate_mode.png b/media/evas_immediate_mode.png new file mode 100644 index 000000000..08f791777 Binary files /dev/null and b/media/evas_immediate_mode.png differ diff --git a/media/evas_object_display.png b/media/evas_object_display.png new file mode 100644 index 000000000..18c2519e8 Binary files /dev/null and b/media/evas_object_display.png differ diff --git a/media/evas_partial_update.png b/media/evas_partial_update.png new file mode 100644 index 000000000..a30ebfffe Binary files /dev/null and b/media/evas_partial_update.png differ diff --git a/media/evas_redrawing01.png b/media/evas_redrawing01.png new file mode 100644 index 000000000..12ccd9051 Binary files /dev/null and b/media/evas_redrawing01.png differ diff --git a/media/evas_redrawing02.png b/media/evas_redrawing02.png new file mode 100644 index 000000000..235a56193 Binary files /dev/null and b/media/evas_redrawing02.png differ diff --git a/media/evas_redrawing03.png b/media/evas_redrawing03.png new file mode 100644 index 000000000..0d132c9da Binary files /dev/null and b/media/evas_redrawing03.png differ diff --git a/media/evas_redrawing04.png b/media/evas_redrawing04.png new file mode 100644 index 000000000..b81e92651 Binary files /dev/null and b/media/evas_redrawing04.png differ diff --git a/media/evas_redrawing05.png b/media/evas_redrawing05.png new file mode 100644 index 000000000..30f64dbe5 Binary files /dev/null and b/media/evas_redrawing05.png differ diff --git a/media/evas_rendering_main_loop.png b/media/evas_rendering_main_loop.png new file mode 100644 index 000000000..2f75adbbb Binary files /dev/null and b/media/evas_rendering_main_loop.png differ diff --git a/media/evas_retained_mode.png b/media/evas_retained_mode.png new file mode 100644 index 000000000..1c060ae51 Binary files /dev/null and b/media/evas_retained_mode.png differ diff --git a/media/evas_scaling.png b/media/evas_scaling.png new file mode 100644 index 000000000..3cfbedfb2 Binary files /dev/null and b/media/evas_scaling.png differ diff --git a/media/evas_smooth_disabled.png b/media/evas_smooth_disabled.png new file mode 100644 index 000000000..d211c4fd7 Binary files /dev/null and b/media/evas_smooth_disabled.png differ diff --git a/media/evas_smooth_enabled.png b/media/evas_smooth_enabled.png new file mode 100644 index 000000000..b579d592b Binary files /dev/null and b/media/evas_smooth_enabled.png differ diff --git a/pages/docs.txt b/pages/docs.txt index 0c7cac9a9..7c671cedd 100644 --- a/pages/docs.txt +++ b/pages/docs.txt @@ -60,6 +60,7 @@ Go check the current available version of EFL on each distro/platform: * [[program_guide/containers_pg|Containers PG]] * [[program_guide/widgets_pg|Widgets PG]] * [[program_guide/event_effect_pg|Event and Effect PG]] + * [[program_guide/evas_pg|Evas PG]] === Samples === diff --git a/pages/program_guide/evas/clipping_objects.txt b/pages/program_guide/evas/clipping_objects.txt new file mode 100644 index 000000000..d90773634 --- /dev/null +++ b/pages/program_guide/evas/clipping_objects.txt @@ -0,0 +1,48 @@ +~~Title: Clipping Objects~~ +{{page>index}} +------ +===== Clipping Objects ===== + +==== Limiting Visibility ==== + +An Evas object can be clipped – in other words, its visible area is restricted +with the clipper object. + +It is often necessary to show only parts of an object, and while it may be +possible to create an object that corresponds only to the part that must be +shown (which is not always possible), it is usually easier to use a clipper. A +clipper is a rectangle that defines what is visible and what is not. The way +to do this is to create a solid white rectangle (by default, so you need not +use ''evas_object_color_set()'') and give it a position and size of what is +wanted visible. The following code exemplifies showing the center half of +my_evas_object: + + +Evas_Object *clipper = evas_object_rectangle_add(evas_canvas); +evas_object_move(clipper, my_evas_object_x / 4, my_evas_object_y / 4); +evas_object_resize(clipper, my_evas_object_width / 2, my_evas_object_height / 2); +evas_object_clip_set(my_evas_object, clipper); +evas_object_show(clipper); + + +==== Layer of Color ==== + +A solid white clipper does not produce a change in the color of the clipped +object, only hides what is outside the clipper's area. Changing the color of +an object is accomplished by using a colored clipper. Clippers with color +function by multiplying the colors of the clipped object. The following code +shows how to remove all the red from an object. + + +Evas_Object *clipper = evas_object_rectangle_add(evas); +evas_object_move(clipper, my_evas_object_x, my_evas_object_y); +evas_object_resize(clipper, my_evas_object_width, my_evas_object_height); +evas_object_color_set(clipper, 0, 255, 255, 255); +evas_object_clip_set(obj, clipper); +evas_object_show(clipper); + + +\\ +----- +{{page>index}} + diff --git a/pages/program_guide/evas/evas_engines_concept.txt b/pages/program_guide/evas/evas_engines_concept.txt new file mode 100644 index 000000000..e68626065 --- /dev/null +++ b/pages/program_guide/evas/evas_engines_concept.txt @@ -0,0 +1,27 @@ +~~Title: Evas Engines Concept~~ +{{page>index}} +----- +===== Evas Engines Concept ===== + +Evas delegates most of the actual rendering work to its engines. Engines are +the backends that Evas uses to render (primitive) objects on a canvas. The +canvas can be the screen, or a buffer in the memory. + +Evas can work with and provides multiple engines, such as (this list is +non-exhaustive): + + * buffer: all the rendering takes place in a buffer + * fb: the rendering takes place in the system's framebuffer + * software_x11: this is the most used, using X11 + * gl_x11: this also renders to an X11 window, except that it uses OpenGL + +These implement the rendering of all the basic objects by themselves, because +they often can be accelerated by the hardware or backend software libraries to +provide fast rendering. + +If a particular engine does not have the provision for a certain primitive +object, it reverts back to using a default software version. + +\\ +----- +{{page>index}} diff --git a/pages/program_guide/evas/evas_object.txt b/pages/program_guide/evas/evas_object.txt new file mode 100644 index 000000000..dbecfa6e1 --- /dev/null +++ b/pages/program_guide/evas/evas_object.txt @@ -0,0 +1,299 @@ +~~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]]). + * [[/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]]) + * [[/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, [[/program_guide/evas/image_objects|images]], +[[/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. + + +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); + + +== 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 == + +[[/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]]). + + +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); + + +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 [[/program_guide/evas/textblock_objects|Textblock]] section. + +=== Image === + +See [[/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]]). + + +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); + + +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}} diff --git a/pages/program_guide/evas/image_objects.txt b/pages/program_guide/evas/image_objects.txt new file mode 100644 index 000000000..4a6652c8d --- /dev/null +++ b/pages/program_guide/evas/image_objects.txt @@ -0,0 +1,413 @@ +~~Title: Image Objects~~ +{{page>index}} +----- +===== Image Objects ===== + +Using Evas, you can create and manipulate image objects. Evas supports image +loaders of various formats as plug-in modules. + +The image formats that Evas supports include ''bmp'', ''edj'', ''gif'', +''ico'', ''jpeg'', ''pmaps'', ''png'', ''psd'', ''svg'', ''tga'', ''tiff'', +''wbmp'', ''webp'', and ''xpm''. + +{{ :evas_image_loader.png }} + +=== Table of Contents === + + * [[#Evas_Object_Image_Functions|Evas Object Image Functions]] + * [[#Creating_an_Image_Object_and_Setting_the_Image_Data_Source|Creating an Image Object and Setting the Image Data Source]] + * [[#Image_Scaling|Image Scaling]] + * [[#Setting_Raw_Data_to_Image_Object|Setting Raw Data to Image Object]] + +=== Related Info === + + * [[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Evas__Object__Image.html|Image Object Functions API]] + +==== Evas Object Image Functions ==== + +Evas has over 70 image object functions. The following functions are discussed +in this document: + + +Evas_Object *evas_object_image_add(Evas *e); +void evas_object_image_file_set(Evas_Object *obj, const char *file, const char *key); +void evas_object_image_fill_set(Evas_Object *obj, int x, int y, int w, int h); +void evas_object_image_filled_set(Evas *e, Eina_Bool setting); +Evas_Object *evas_object_image_filled_add(Evas *e); +void evas_object_image_smooth_scale_set(Evas_Object *obj, Eina_Bool smoothscale); +void evas_object_image_load_size_set(Evas_Object *obj, int w, int h); +void evas_object_image_data_set(Evas_Object *obj, void *data); +void *evas_object_image_data_get(const Evas_Object *obj, Eina_Bool for_writing); +void evas_object_image_size_set(Evas_Object *obj, int w, int h); +void evas_object_image_data_update_add(Evas_Object *obj, int x, int y, int w, int h); +Eina_Bool evas_object_image_save(const Evas_Object *obj, const char *file, const char *key, const char *flags); + + +==== Creating an Image Object and Setting the Image Data Source ==== + +A common use case of an image object is to set a file as the image data +source. The process has 3 steps and each one involves the following API calls: + + + * The ''evas_object_image_add()'' function creates an image object and returns the pointer. + +Evas_Object *evas_object_image_add(Evas *e); + + * The ''evas_object_image_file_set()'' function sets a source file on the image object. The object fetches the image pixel data from the source file. + +void evas_object_image_file_set(Evas_Object *obj, const char *file, const char *key); + + * The ''evas_object_image_fill_set()'' sets how to fill the image object's area with the given pixel data. + +void evas_object_image_fill_set(Evas_Object *obj, int x, int y, int w, int h); + + +In the following code example, the ''main()'' function creates an image object +and displays it on a window. The image object size is 300x300 and the source +image resolution is 100x127. The image is scaled into 300 by 300 to fill the +image object area using the ''evas_object_image_fill_set()'' function. + + +#include + +int main(int argc, char **argv) +{ + elm_init(argc, argv); + + // Create a window object + Evas_Object *win = elm_win_add(NULL, "main", ELM_WIN_BASIC); + evas_object_resize(win, 400, 400); + evas_object_show(win); + + // Return Evas handle from window + Evas *e = evas_object_evas_get(win); + + // Create an image object + Evas_Object *img = evas_object_image_add(e); + + // Set a source file to fetch pixel data + evas_object_image_file_set(img, "./logo.png", NULL); + + // Set the size and position of the image on the image object area + evas_object_image_fill_set(img, 0, 0, 300, 300); + + evas_object_move(img, 50, 50); + evas_object_resize(img, 300, 300); + evas_object_show(img); + + elm_run(); + elm_shutdown(); + + return 0; +} + + +{{ :evas_object_display.png }} + +==== Image Scaling ==== + +Users can decide how to fill the image object area with the given image pixel +data by setting the position, width, and height of the image using the +''evas_object_image_fill_set()'' function. Without setting this information, +the image is not displayed. If the size of the image is bigger than the image +object area, only a sub-region of the original image is displayed. If the +image is smaller than the area, images are tiled repeatedly to fill the object +area. + +{{ :evas_image_scaling.png }} + +{{ :evas_scaling.png }} + +the ''evas_object_image_filled_set()'' function scales the image to fit the +object area. Resizing the image object automatically triggers an internal call +to the ''evas_object_image_fill_set()'' function. + + +void evas_object_image_filled_set(Evas * e, + Eina_Bool setting + ) + + +The ''evas_object_image_filled_add()'' function creates a new image object +that automatically scales its bound image to the object area. This is a helper +function around the ''evas_object_image_add()'' and +''evas_object_image_filled_set()'' functions. + +Scaled images' quality can differ according to scaling algorithms. Smooth +scaling improves the image quality in the process of size reducing or +enlarging. Evas runs its own smooth scaling algorithm by default and provides +an API so users can disable the function. + + +Evas_Object *evas_object_image_filled_add(Evas *e); + + + +void evas_object_image_smooth_scale_set(Evas_Object * obj, + Eina_Bool smoothscale + ) + + +The algorithm is implemented using the SIMD (Single Instruction Multiple Data) +vectorization in case of software rendering. It is optimized on Intel and ARM +CPU through MMX and NEON command respectively. + +There is a trade-off between image smoothness and rendering performance. The +load gets bigger as the image gets bigger. Users can avoid such scaling +overload by using the same size of the image object and the source image. + +In the following code, 2 image objects are created to show the effects of +smooth scaling. The one with smooth scaling applied appears softer on the +screen. + + + +#include + +int main(int argc, char **argv) +{ + elm_init(argc, argv); + + // Create a window object + Evas_Object *win = elm_win_add(NULL, "main", ELM_WIN_BASIC); + evas_object_resize(win, 400, 200); + evas_object_show(win); + + // Return Evas handle from window + Evas *e = evas_object_evas_get(win); + + // Create an image object + Evas_Object *img = evas_object_image_filled_add(e); + evas_object_image_file_set(img, "./logo.png", NULL); + evas_object_move(img, 0, 0); + evas_object_resize(img, 200, 200); + evas_object_show(img); + + // Create another image object + Evas_Object *img2 = evas_object_image_filled_add(e); + evas_object_image_file_set(img2, "./logo.png", NULL); + + // Disable smooth scaling + evas_object_image_smooth_scale_set(img2, EINA_FALSE); + evas_object_move(img2, 200, 0); + evas_object_resize(img2, 200, 200); + evas_object_show(img2); + + elm_run(); + + elm_shutdown(); + + return 0; +} + + +Smooth scaling disabled: + +{{ :evas_smooth_disabled.png }} + +Smooth scaling enabled: + +{{ :evas_smooth_enabled.png }} + +Evas caches scaled image data and reuses them. Users can save the memory by +loading the image in the scaled size to the memory at the beginning. This +option is available only for ''jpeg'' format at the moment. + + +void evas_object_image_load_size_set(Evas_Object * obj, + int w, + int h + ) + + +An example code is as follows. + + + +#include + +int main(int argc, char **argv) +{ + elm_init(argc, argv); + + // Create a window object + Evas_Object *win = elm_win_add(NULL, "main", ELM_WIN_BASIC); + evas_object_resize(win, 400, 200); + evas_object_show(win); + + // Return Evas handle from window + Evas *e = evas_object_evas_get(win); + + // Create an image object + Evas_Object *img = evas_object_image_filled_add(e); + + // Load the image scaled into the object size + // before evas_object_image_file_set() is called + evas_object_image_load_size_set(img, 300, 300); + + evas_object_image_file_set(img, "./logo.png", NULL); + + evas_object_move(img, 50, 50); + evas_object_resize(img, 300, 300); + evas_object_show(img); + + elm_run(); + + elm_shutdown(); + + return 0; +} + + +==== Setting Raw Data to Image Object ==== + +Users can set raw data to the image object manually using the +''evas_object_image_data_set()'' function instead of setting an image file as +the data source. The image data should be in raw data form. In case of an +200x200 sized image with alpha channel enabled (32 bits per pixel), the size +of the image data is 14000 (=200*200*4) bytes. + + +void evas_object_image_data_set(Evas_Object * obj, + void * data + ) + + +Image objects fetch metadata such as width or height from the header of the +image files. Since the raw data does not have the metadata, users must set the +size of the image using the ''evas_object_image_size_set()'' function. + + +void evas_object_image_size_set(Evas_Object * obj, + int w, + int h + ) + + +The ''evas_object_image_data_get()'' function returns the data pointer of an +image object and requires a parameter to determine whether the data is +modified or not. If users pass ''EINA_TRUE'' for ''for_writing'', Evas updates +the image pixels in the next rendering cycle. + + +void* evas_object_image_data_get(const Evas_Object * obj, + Eina_Bool for_writing + ) + + +The ''evas_object_image_data_update_add()'' helps to mark the updated area for +rendering efficiency. + + +void evas_object_image_data_update_add(Evas_Object * obj, + int x, + int y, + int w, + int h + ) + + +The following example code and figure show how to specify the area to update. + + +evas_object_image_data_update_add(image, 100, 100, 50, 50); +evas_object_image_data_update_add(image, 180, 100, 50, 50); +evas_object_image_data_update_add(image, 85, 200, 160, 80); + + +{{ :evas_partial_update.png }} + +The following code creates an image object and sets a source file on it. Then +it implements the blur effect to the pixel data and saves them using the +''evas_object_image_save()'' function. + + +Eina_Bool evas_object_image_save(const Evas_Object * obj, + const char * file, + const char * key, + const char * flags + ) + + + +#include + +void image_blur(Evas_Object *img) +{ + unsigned char *img_src = evas_object_image_data_get(img, EINA_TRUE); + + int w, h; + evas_object_image_size_get(img, &w, &h); + int blur_size = 4; + int x, y, xx, yy; + + for (y = 0; y < h; y++) + { + for (x = 0; x < w; x++) + { + int avg_color[3] = {0, 0, 0}; + int blur_pixel_cnt = 0; + + for (xx = x; (xx < x + blur_size) && (xx < w); xx++) + { + for (yy = y; (yy < y + blur_size) && (yy < h); yy++) + { + int idx = (yy * w * 4) + (xx * 4); + avg_color[0] += img_src[idx + 0]; + avg_color[1] += img_src[idx + 1]; + avg_color[2] += img_src[idx + 2]; + ++blur_pixel_cnt; + } + } + avg_color[0] /= blur_pixel_cnt; + avg_color[1] /= blur_pixel_cnt; + avg_color[2] /= blur_pixel_cnt; + + for (xx = x; (xx < x + blur_size) && (xx < w); xx++) + { + for (yy = y; (yy < y + blur_size) && (yy < h); yy++) + { + int idx = (yy * w * 4) + (xx * 4); + img_src[idx + 0] = avg_color[0]; + img_src[idx + 1] = avg_color[1]; + img_src[idx + 2] = avg_color[2]; + } + } + } + } + evas_object_image_data_update_add(img, 0, 0, w, h); +} + +int main(int argc, char **argv) +{ + elm_init(argc, argv); + + Evas_Object *win = elm_win_add(NULL, "main", ELM_WIN_BASIC); + evas_object_resize(win, 200, 200); + evas_object_show(win); + + Evas *e = evas_object_evas_get(win); + + Evas_Object *img = evas_object_image_filled_add(e); + evas_object_image_file_set(img, "./logo.png", NULL); + evas_object_resize(img, 200, 200); + evas_object_show(img); + + image_blur(img); + + evas_object_image_save(img, "logo2.png", NULL, "quality=100 compress=8"); + + elm_run(); + elm_shutdown(); + + return 0; +} + + +Before: {{ :evas_blur1.png }} + +After: {{ :evas_blur2.png }} + +\\ +----- +{{page>index}} diff --git a/pages/program_guide/evas/index.txt b/pages/program_guide/evas/index.txt new file mode 100644 index 000000000..5a198712b --- /dev/null +++ b/pages/program_guide/evas/index.txt @@ -0,0 +1,7 @@ +++++Evas Menu| +^ [[/program_guide/evas_pg|Evas Programming Guide]] ([[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/evas_main.html|Evas API]]) ^^^ +| [[program_guide/evas/rendering_concept_and_method_in_evas|Rendering Concept and Method in Evas]] | [[program_guide/evas/evas_object|Evas Object]] | [[program_guide/evas/clipping_objects|Clipping Objects]] | +| [[program_guide/evas/mapping_objects|Mapping Objects]] | [[program_guide/evas/evas_engines_concept|Evas Engines Concept]] | [[program_guide/evas/ui_rendering_mode|UI Rendering Mode]] | +++++ + + diff --git a/pages/program_guide/evas/mapping_objects.txt b/pages/program_guide/evas/mapping_objects.txt new file mode 100644 index 000000000..17b047215 --- /dev/null +++ b/pages/program_guide/evas/mapping_objects.txt @@ -0,0 +1,180 @@ +~~Title: Mapping Objects~~ +{{page>index}} +----- +===== Mapping Objects ===== + +Evas allows different transformations to be applied to all kinds of objects. +These are applied by means of UV mapping. With UV mapping, one map points in +the source object to a 3D space positioning at target. This allows rotation, +perspective, scale, and many other effects depending on the map that is used. + +=== Table of Contents === + + * [[#Creating_a_Map_|Creating a Map ]] + * [[#Manual_Point_Setting|Manual Point Setting]] + * [[#Applying_a_Map_|Applying a Map ]] + * [[#Basic_Utility_Functions_|Basic Utility Functions ]] + * [[#3D_Utility_Functions_|3D Utility Functions ]] + * [[#Color_and_Lighting_|Color and Lighting ]] + +=== Related Info === + + * [[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Evas__Object__Group__Map.html|UV Mapping (Rotation, Perspective, 3D...) API]] + +==== Creating a Map ==== + +A map consists of a set of points, but currently only four are supported. Each +of these points contains a set of canvas coordinates x and y that are used to +alter the geometry of the mapped object, and a z coordinate that indicates the +depth of that point. This last coordinate does not normally affect the map, +but is used by several of the utility functions to calculate the right +position of the point given other parameters. + +The coordinates for each point are set with ''evas_map_point_coord_set(map, +index, x, y, z)''. In the example below, there is a rectangle whose +coordinates are (100, 100) and (300, 300). + + +Evas_Object *object = evas_object_rectangle_add(evas); +evas_object_move(object, 100, 100); +evas_object_resize(object, 200, 200); +Evas_Map map = evas_map_new(4); +evas_map_point_coord_set(map, 0, 100, 100, 0); +evas_map_point_coord_set(map, 1, 300, 100, 0); +evas_map_point_coord_set(map, 2, 300, 300, 0); +evas_map_point_coord_set(map, 3, 100, 300, 0); + + +There are functions to ease the process. + +Use ''evas_map_util_points_populate_from_geometry(map, x, y, w, h, z)'', where +the map coordinates are set to the given rectangle, and ''z'' is the +coordinate in the Z axis, which is the same for all points. + + +Evas_Object *object = evas_object_rectangle_add(evas); +evas_object_move(object, 100, 100); +evas_object_resize(object, 200, 200); +Evas_Map map = evas_map_new(4); +evas_map_util_points_populate_from_geometry(map, 100, 100, 200, 200, 0); + + +You can also use ''evas_map_util_points_populate_from_object(map, object)''. + + +Evas_Object *object = evas_object_rectangle_add(evas); +evas_object_move(object, 100, 100); +evas_object_resize(object, 200, 200); +Evas_Map map = evas_map_new(4); +evas_map_util_points_populate_from_object(map, object); + + +You can also use ''evas_map_util_points_populate_from_object_full(map, object, +z)'', where ''z'' is the coordinate in the Z axis, which is the same for all +points. + + +Evas_Object *object = evas_object_rectangle_add(evas); +evas_object_move(object, 100, 100); +evas_object_resize(object, 200, 200); +Evas_Map map = evas_map_new(4); +evas_map_util_points_populate_from_object_full(map, object, 0); + + +==== Manual Point Setting ==== + +Several effects are applied to an object by setting each point of the map to +the right coordinates. For example, a simulated perspective is achieved as +follows. + + +evas_map_point_coord_set(map, 0, 300, 100, 0); +evas_map_point_coord_set(map, 1, 450, 120, 0); +evas_map_point_coord_set(map, 2, 450, 260, 0); +evas_map_point_coord_set(map, 3, 300, 300, 0); + + +The Z coordinate is not used when setting points by hand; thus its value is +not important. + +==== Applying a Map ==== + +Regardless of the specific way you create a map, to apply it to a specific +object, use + + +evas_object_map_set(object, map); +evas_object_map_enable_set(object, EINA_TRUE); + + +==== Basic Utility Functions ==== + +Evas provides utility functions for common transformations: + + * ''evas_map_util_rotate(map, angle, cx, cy)'': This performs a rotation of the ''angle'' degrees around the center point with the coordinates (cx, cy). + * ''evas_map_util_zoom(map, zoomx, zoomy, cx, cy)'': This performs a ''zoomx'' and ''zoomy'' zoom in the X and Y directions respectively, with the center point with the coordinates (cx, cy). + + +For example, the following code rotates an object around its center. + + +int x, y, w, h; +evas_object_geometry_get(object, &x, &y, &w, &h); +Evas_Map *map = evas_map_new(4); +evas_map_util_points_populate_from_object(map, object); +evas_map_util_rotate(map, 45, x + (w / 2), y + (h / 2)); +evas_object_map_set(object, map); +evas_object_map_enable_set(object, EINA_TRUE); +evas_map_free(m); + + +The following code rotates an object around the center of the window. + + +int w, h; +evas_output_size_get(evas, &w, &h); +Evas_Map *map = evas_map_new(4); +evas_map_util_points_populate_from_object(map, object); +evas_map_util_rotate(map, 45, w / 2, h / 2); +evas_object_map_set(object, map); +evas_object_map_enable_set(object, EINA_TRUE); +evas_map_free(m); + + +==== 3D Utility Functions ==== + +Evas provides utility functions for 3D transformations. + +To make a 3D rotation, use ''evas_map_util_3d_rotate(map, anglex, angley, +anglez, cx, cy, cz)''. With this code, you can set the Z coordinate of the +rotation center, and the angles to rotate through around all axes. + +Rotating in the 3D space does not look natural. A more natural look becomes by +adding perspective to the transformation, which is done with +''evas_map_util_3d_perspective(map, px, py, z0, focal)'' on the map after its +position has been set. + + * ''px'' and ''py'' specify the "infinite distance" point in the 3D conversion, where all lines converge to. + * ''z0'' specifies the Z value at which there is a 1:1 mapping between spatial coordinates and screen coordinates: any points on this Z value do not have their X and Y coordinates modified in the transform, while those further away (Z value higher) shrink into the distance, and those less than this value expand. + * ''focal'' determines the "focal length" of the camera: this is the distance in reality between the camera lens plane (the rendering results are undefined at or closer than this) and the ''z0'' value; this function allows for some "depth" control. + + +==== Color and Lighting ==== + +Each point in a map can be set to a color, which is multiplied with the +object's own color and linearly interpolated in between adjacent points. To do +this, use ''evas_map_point_color_set(map, index, r, g, b, a)'' for each point +of the map, or ''evas_map_util_points_color_set(map, r, g, b, a)'' to set +every point into the same color. + +To add lighting for the objects, which is useful with 3D transforms, use +''evas_map_util_3d_lighting(map, lightx, lighty, lightz, lightr, lightg, +lightb, ambientr, ambientg, ambientb)'': + + * ''lightx'', ''lighty'' and ''lightz'' are the local light source coordinates; + * ''lightr'', ''lightg'' and ''lightb'' are the local light source colors; + * ''ambientr'', ''ambientg'' and ''ambientb'' are the ambient light colors. Evas sets the color of each point based on the distance to the light source, the angle with which the object is facing the light and the ambient light. The orientation of each point is important. If the map is defined counter-clockwise, the object faces away from the user and becomes obscured, since no light does not reflect from it. + +\\ +------ +{{page>index}} diff --git a/pages/program_guide/evas/rendering_concept_and_method_in_evas.txt b/pages/program_guide/evas/rendering_concept_and_method_in_evas.txt new file mode 100644 index 000000000..bd2e8ff65 --- /dev/null +++ b/pages/program_guide/evas/rendering_concept_and_method_in_evas.txt @@ -0,0 +1,116 @@ +~~Title: Rendering Concept and Method in Evas~~ +{{page>index}} +----- +===== Rendering Concept and Method in Evas ===== + +Evas is a canvas display library. It is markedly different from most display +and windowing systems as the canvas is structural and is also a state engine, +whereas most display and windowing systems are immediate mode display targets. +Evas handles the logic between a structural display via its state engine, and +controls the target windowing system in order to produce rendered results of +the current canvas' state on the display. + +Immediate mode display systems retain very little or no state. A program +executes a series of commands, as in the following pseudo code. + + +draw line from position (0, 0) to position (100, 200); + +draw rectangle from position (10, 30) to position (50, 500); + +bitmap_handle = create_bitmap(); +scale bitmap_handle to size 100 x 100; +draw image bitmap_handle at position (10, 30); + + +The series of commands is executed by the windowing system and the results are +typically displayed on the screen. Once the commands are executed, the display +system does not know how to reproduce this image again, and has to be +instructed by the application on how to redraw sections of the screen if +needed. Each successive command is executed as instructed by the application +and either emulated by software or sent to the graphics hardware on the device +to be performed. + +The advantage of such a system is that it is simple and gives a program tight +control over how something looks and is drawn. Given the increasing complexity +of displays and demands by users to have better looking interfaces, more work +needs to be done at this level by the internals of widget sets, custom display +widgets and other programs. This means that more logic and display rendering +code needs to be written again each time the application needs to figure out +how to minimize redraws so that display is fast and interactive, and keep +track of redraw logic. + +For example, if in the scene below, the windowing system requires the +application to redraw the area from 0, 0 to 50, 50 (also referred to as the +"expose event"). Then the programmer calculates manually the updates and +repaints it again. + + +Redraw from position (0, 0) to position (50, 50): + +// What was in area (0, 0, 50, 50)? + +// 1. intersection part of line (0, 0) to (100, 200)? + draw line from position (0, 0) to position (25, 50); + +// 2. intersection part of rectangle (10, 30) to (50, 500)? + draw rectangle from position (10, 30) to position (50, 50) + +// 3. intersection part of image at (10, 30), size 100 x 100? + bitmap_subimage = subregion from position (0, 0) to position (40, 20) + draw image bitmap_subimage at position (10, 30); + + +If all elements in the above scene are opaque, the system is doing useless +paints: part of the line is behind the rectangle, and part of the rectangle is +behind the image. These useless paints tend to be very costly. + +Evas is a structural system in which the programmer creates and manages +display objects and their properties, and as a result of this higher level +state management, the canvas is able to redraw the set of objects when needed +to represent the current state of the canvas. + +For example, see the following pseudo code. + + +line_handle = create_line(); +set line_handle from position (0, 0) to position (100, 200); +show line_handle; + +rectangle_handle = create_rectangle(); +move rectangle_handle to position (10, 30); +resize rectangle_handle to size 40 x 470; +show rectangle_handle; + +bitmap_handle = create_bitmap(); +scale bitmap_handle to size 100 x 100; +move bitmap_handle to position (10, 30); +show bitmap_handle; + +render scene; + + +This looks longer, but when the display needs to be refreshed or updated, the +programmer only moves, resizes, shows, hides etc. the objects that need to +change. The programmer thinks at the object logic level, and the canvas +software does the rest of the work, figuring out what changed in the canvas +since it was last drawn, how to most efficiently redraw the canvas and its +contents to reflect the current state, and doing the actual drawing of the +canvas. + +This allows the programmer think in a more natural way when dealing with a +display, and saves time and effort of working out how to load and display +images, to render given the current display system etc. Since Evas is portable +across different display systems, this gives the programmer the ability to +port and display the code on different display systems with little work. + +Evas is a display system somewhere between a widget set and an immediate mode +display system. It retains basic display logic, but does little high-level +logic such as scrollbars, sliders, push buttons etc. + +For more information on the UI rendering modes (immediate and retained), see +[[/program_guide/evas/ui_rendering_mode|UI Rendering Mode]]. + +\\ +----- +{{page>index}} diff --git a/pages/program_guide/evas/textblock_objects.txt b/pages/program_guide/evas/textblock_objects.txt new file mode 100644 index 000000000..9c075413f --- /dev/null +++ b/pages/program_guide/evas/textblock_objects.txt @@ -0,0 +1,64 @@ +~~Title: Textblock Objects~~ +{{page>index}} +----- +===== Textblock Objects ===== + +Unlike basic text objects, a textblock handles complex text, managing multiple +styles and multiline text based on HTML-like tags. However, these extra +features are heavier on memory and processing cost. + +The textblock objects is an object that shows big chunks of text. Textblock +supports many features, including text formatting, automatic and manual text +alignment, embedding items (icons, for example). Textblock has three important +parts: the text paragraphs, the format nodes and the cursors. + +To set markup to format text, use for example +''Big!''. Set more than one style +directive in one tag with ''Big and +Red!''. Please note that we used '''' +although the format also included color. This is because the first format +determines the matching closing tag's name. You can use anonymous tags, such +as ''Big'', which pop any type of format, but it +is advisable to use the named alternatives instead. + +Textblock supports the following formats: + + * ''font'': Font description in fontconfig such as format, for example "Sans:style=Italic:lang=hi". or "Serif:style=Bold". + * ''font_weight'': Overrides the weight defined in "font". For example, "font_weight=Bold" is the same as "font=:style=Bold". The supported weights are "normal", "thin", "ultralight", "light", "book", "medium", "semibold", "bold", "ultrabold", "black", and "extrablack". + * ''font_style'': Overrides the style defined in "font". For example, "font_style=Italic" is the same as "font=:style=Italic". The supported styles are "normal", "oblique", and "italic". + * ''font_width'': Overrides the width defined in "font". For example, "font_width=Condensed" is the same as "font=:style=Condensed". The supported widths are "normal", "ultracondensed", "extracondensed", "condensed", "semicondensed", "semiexpanded", "expanded", "extraexpanded", and "ultraexpanded". + * ''lang'': Overrides the language defined in "font". For example, "lang=he" is the same as "font=:lang=he". + * ''font_fallbacks'': A comma delimited list of fonts to try if finding the main font fails. + * ''font_size'': The font size in points. + * ''font_source'': The source of the font, for example an eet file. + * ''color'': The text color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA". + * ''underline_color'': The color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA". + * ''underline2_color'': The color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA". + * ''outline_color'': The color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA". + * ''shadow_color'': The color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA". + * ''glow_color'': The color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA". + * ''glow2_color'': The color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA". + * ''strikethrough_color'': The color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA". + * ''align'': The text alignment in one of the following formats: "auto" (according to text direction), "left", "right", "center" or "middle", which take a value between 0.0 and 1.0 or a value between 0% to 100%. + * ''valign'': The vertical text alignment in one of the following formats: "top", "bottom", "middle", "center", "baseline" or "base", which take a value between 0.0 and 1.0 or a value between 0% to 100%. + * ''wrap'': The text wrap in one of the following formats: "word", "char", "mixed", or "none". + * ''left_margin'': Either "reset" or a pixel value indicating the margin. + * ''right_margin'': Either "reset" or a pixel value indicating the margin. + * ''underline'': The style of underlining in one of the following formats: "on", "off", "single", or "double". + * ''strikethrough'': The style of text that is either "on" or "off". + * ''backing_color'': The background color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA". + * ''backing'': The background color enabled or disabled: "on" or "off". + * ''style'': The style of the text in one of the following formats: "off", "none", "plain", "shadow", "outline", "soft_outline", "outline_shadow", "outline_soft_shadow", "glow", "far_shadow", "soft_shadow" or "far_soft_shadow". The direction is selected by adding "bottom_right", "bottom", "bottom_left", "left", "top_left", "top", "top_right" or "right". For example, "style=shadow,bottom_right". + * ''tabstops'': The pixel value for tab width. + * ''linesize'': To force a line size in pixels. + * ''linerelsize'': Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size. + * ''linegap'': To force a line gap in pixels. + * ''linerelgap'': Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size. + * ''item'': Creates an empty space that is filled by an upper layer. Use "size", "abssize", or "relsize" to define the item"s size, and an optional vsize = full/ascent to define the item's position in the line. + * ''linefill'': Either a float value or percentage indicating how much to fill the line. + * ''ellipsis'': A value between 0.0 and 1.0 to indicate the type of ellipsis, or -1.0 to indicate that an ellipsis is not wanted. + * ''password'': Either "on" or "off", this is used to specifically turn replacing chars with the password mode (that is, replacement char) on and off. + +\\ +----- +{{page>index}} diff --git a/pages/program_guide/evas/ui_rendering_mode.txt b/pages/program_guide/evas/ui_rendering_mode.txt new file mode 100644 index 000000000..2f0b53087 --- /dev/null +++ b/pages/program_guide/evas/ui_rendering_mode.txt @@ -0,0 +1,172 @@ +~~Title: UI Rendering Mode~~ +{{page>index}} +----- +===== UI Rendering Mode ===== + +Evas removes the need to know about the characteristics of your display system +or what graphics calls are used to draw them and how. It deals on an object +level where all you do is create and manipulate objects in a canvas, set their +properties, and the rest is done for you. This rendering method is called the +retained mode, whereas the immediate mode is an alternative rendering method. + +=== Table of Contents === + + * [[#Immediate_Mode|Immediate Mode]] + * [[#Retained_Mode|Retained Mode]] + * [[#Evas_Rendering|Evas Rendering]] + +==== Immediate Mode ==== + +The immediate mode is the most commonly used in graphics toolkit libraries, +such as GTK+, GDI, and GDI+. The application is responsible for repainting the +portion of the client area that is invalidated. + +{{ :evas_immediate_mode.png }} + +The application commands any drawing issues as it needs, and the display +system draws some GUIs. After the drawing is done, it appears in the +destination. This mode allows you to have a exact control over the render +cycles. However, if the draw commands are misused, unnecessary drawing can be +performed or drawing never happen at all. + +The following example explains the common usage of the immediate mode: + + +void update() +{ + Image *img = load_image(NEW_IMG); + + // Switch button image to new one + update_button_image(img); + + // Issue the invalidate area (button area) to be redrawn on the screen + invalidate_area(button_x, button_y, button_w, button_h); + + // Move rectangle from (200, 200) to (300, 300) + int rect_prev_x = rect_x; + int rect_prev_y = rect_y; + rectangle_x = 300; + rectangle_y = 300; + set_rect_position(rect_x, rect_y); + + // Issue the invalidate area (changed area) to be redrawn on the screen + int diff_x = rect_x – rect_prev_x; + int diff_y = rect_y – rect_prev_y; + invalidate_area(rect_prev_x, rect_prev_y, (rect_w + diff_x), (rect_h + diff_y)); + + + // After setting the invalidate area, request rendering to update the screen + render(); + + // Now you can see how the button image and rectangle position are changed +} + + +==== Retained Mode ==== + +A graphics system adopting the retained mode is basically responsible for +responding to all repaint requests for rendering the application objects. +Clients do not directly cause actual rendering, but objects are redrawn when +parts of them are updated. + +{{ :evas_retained_mode.png }} + +Since Evas works with the retained mode, there is no need to command any +drawings. The following example shows how to write a GUI code with Evas for +your application: + + + +void create_image() +{ + // Initialize an image object to be displayed on the screen + Evas_Object *img = evas_object_image_add(e); + + // Set image resource + evas_object_image_file_set(img, IMG, NULL); + + // Set image position + evas_object_move(img, 100, 100); + + // Set image size + evas_object_resize(img, 200, 200); + + // Set image visibility (show or hide) + evas_object_show(img); +} + +void create_rectangle() +{ + // Initialize an rectangle object to be displayed on the screen + Evas_Object *rect = evas_object_rectangle_add(e); + + // Set rectangle color + evas_object_color_set(rect, 255, 0, 0, 255); + + // Set rectangle position + evas_object_move(rect, 200, 200); + + // Set rectangle size + evas_object_resize(rect, 200, 200); + + // Set rectangle visibility (show or hide) + evas_object_show(rect); +} + + +A few main loops later you can replace the image with another one and move the +rectangle. You only need to set a new image file to the image object and move +the rectangle object. Evas computes the invalidate area and redraws the image +and rectangle behind the application when it's on rendering time. + + +void update() +{ + // Set new image resource + elm_image_file_set(img, NEW_IMG, NULL); + + // Set new rectangle position + evas_object_move(rect, 300, 300); +} + + +==== Evas Rendering ==== + +EFL and/or Elementary applications work on the ecore main loop, and the loop +goes on a few steps for every frame. Evas redraws some changes in the objects +when the main loop goes to the idle enterer step. If there are no changes, +Evas rendering is skipped. Otherwise, Evas calculates any changed portions of +all display objects and redraws them. + +{{ :evas_rendering_main_loop.png }} + +To minimize the rendering, Evas tracks the states of all display objects, such +as position, size, visibility, and color. Even if some of these states are +changed but the object is hidden by other obscured objects, it is not redrawn. +In other words, Evas draws only the necessary changes in the screen. + +The following figures illustrate how Evas redraws the changed area: + + * In the first example, there is a blue-color background object (a sky-blue color rectangle) and a partially hidden cloud image object. Above them, there are a red and green rectangle, and the "Hello out there" text is printed on the green rectangle. +{{ :evas_redrawing01.png }} + * In the second example, some of the objects have moved (the cloud image is moved to right and the green rectangle is moved downwards). +{{ :evas_redrawing02.png }} + * As a result, the third example illustrates some regions that require updates. +{{ :evas_redrawing03.png }} + * Evas decides which portions are invalid and to be redrawn. The fourth example shows the cleaned portion of the screen, which is the redrawn area. + +Evas redraws the content only in the redrawn portions. + +{{ :evas_redrawing04.png }} + + * Finally, the fifth example shows how the screen is updated and the result is visible. +{{ :evas_redrawing05.png }} + +If Evas worked in an immediate mode style, the application would need to +calculate the changed areas themselves, adding extra work. With Evas, you can +let Evas figure out the updates and you can yourself concentrate on the +application and UI core and logic. + +\\ +----- +{{page>index}} diff --git a/pages/program_guide/evas_pg.txt b/pages/program_guide/evas_pg.txt new file mode 100644 index 000000000..23b58ab30 --- /dev/null +++ b/pages/program_guide/evas_pg.txt @@ -0,0 +1,68 @@ +~~Title: Evas Programming Guide~~ +{{page>index}} +===== Evas Programming Guide ===== + +Evas is a clean display canvas API for several target display systems that can +draw anti-aliased text, smooth super and sub-sampled scaled images, +alpha-blend objects and much more. + +It abstracts any need to know much about what the characteristics of your +display system are, what graphics calls are used to draw them, and how. It +deals on an object level where all you do is create and manipulate objects in +a canvas and set their properties. + +Evas optimizes the rendering pipeline to minimize effort in redrawing changes +made to the canvas and so takes this work out of the programmers hand, saving +a lot of time and energy. + +It is designed to work on embedded systems all the way to large and powerful +multi-cpu workstations. It can be compiled to only have the features you need +for your target platform if you so wish. It has several display back-ends, +allowing it display on several display systems, making it portable for +cross-device and cross-platform development. + +Evas is not a widget set or a widget toolkit, but it is their base. See +Elementary for a toolkit based on Evas, Edje, Ecore and other Enlightenment +technologies. + +It is not dependent or aware of main loops, input or output systems. Input +must be polled from various sources and fed to Evas. It does not create +windows or report windows updates to your system, but draws the pixels and +reports to the user the areas that are changed. These operations are ready to +be used in Ecore, particularly in Ecore_Evas wrapper/helper set of functions. + +=== Table of Contents === + + * [[/program_guide/evas/rendering_concept_and_method_in_evas|Rendering Concept and Method in Evas]] + * [[/program_guide/evas/evas_object|Evas Object]] + * [[program_guide/evas/evas_object#Primitive_Renderable_Objects|Primitive Renderable Objects]] + * [[program_guide/evas/evas_object#Rectangle|Rectangle]] ([[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Evas__Object__Rectangle.html|API]]). + * [[program_guide/evas/evas_object#Text|Text]] ([[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Evas__Object__Text.html| API]]). + * [[/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]]) + * [[/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]]) + * [[program_guide/evas/evas_object#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]]) + * [[program_guide/evas/evas_object#Primitive_Container_Objects|Primitive Container Objects]] + * [[program_guide/evas/evas_object#Table|Table]] ([[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Evas__Object__Table.html|API]]) + * [[program_guide/evas/evas_object#Grid|Grid]] ([[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Evas__Object__Grid.html|API]]) + * [[program_guide/evas/evas_object#Box|Box]] ([[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Evas__Object__Box.html|API]]) + * [[/program_guide/evas/clipping_objects|Clipping Objects]] + * [[/program_guide/evas/mapping_objects|Mapping Objects]] + * [[/program_guide/evas/evas_engines_concept|Evas Engines Concept]] + * [[/program_guide/evas/ui_rendering_mode|UI Rendering Mode]] + +=== Related Info === + + * [[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/evas_main.html|Evas API]] + * [[/program_guide/event_effect/evas_smart_events|Evas Smart Object Events PG]] + * [[/program_guide/event_effect/evas_object_events|Evas Object Events PG]] + * [[/program_guide/event_effect/evas_events|Evas Events PG]] + * [[/program_guide/event_effect/evas_map_animations|Evas Map Effects PG]] + +\\ +^ Evas Examples ^^^^^^ +| [[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/Example_Evas_Buffer_Simple.html|Simple Evas canvas]] | [[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/Example_Evas_Init_Shutdown.html|Evas' init/shutdown routines]] | [[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/Example_Evas_Text.html|Evas text object]] | [[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/Example_Evas_Images.html|Some image object functions]] | [[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/Example_Evas_Images_2.html|Some more image object functions]] | [[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/Example_Evas_Events.html|Evas events (canvas and object ones) and some canvas operations]] | +| [[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/Example_Evas_Object_Manipulation.html|Evas objects basic manipulation]] | [[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/Example_Evas_Aspect_Hints.html|Evas aspect hints example]] | [[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/Example_Evas_Size_Hints.html|Evas alignment, minimum size, maximum size, padding and weight hints]] | [[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/Example_Evas_Stacking.html|Evas object stacking functions (and some event handling)]] | [[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/Example_Evas_Smart_Objects.html|Evas object smart objects]] | [[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/Example_Evas_Box.html|Evas box]] | + +\\ +---- +{{page>index}} diff --git a/pages/program_guide/index.txt b/pages/program_guide/index.txt index 597d7cd36..b9fe75388 100644 --- a/pages/program_guide/index.txt +++ b/pages/program_guide/index.txt @@ -3,4 +3,5 @@ * [[program_guide/containers_pg|Container PG]] * [[program_guide/widgets_pg|Widgets PG]] * [[program_guide/event_effect_pg|Event and Effect PG]] + * [[program_guide/evas_pg|Evas PG]] ++++