2011-04-08 00:26:20 -07:00
|
|
|
/**
|
2012-12-18 08:12:56 -08:00
|
|
|
@page evas_main Evas
|
2012-06-13 01:12:36 -07:00
|
|
|
|
2012-12-28 15:26:05 -08:00
|
|
|
@date 2000 (created)
|
2012-06-13 01:12:36 -07:00
|
|
|
|
2020-02-28 02:01:56 -08:00
|
|
|
@section evas_toc Table of Contents
|
2012-06-13 01:12:36 -07:00
|
|
|
|
2012-12-18 08:18:28 -08:00
|
|
|
@li @ref evas_main_intro
|
|
|
|
@li @ref evas_main_work
|
|
|
|
@li @ref evas_main_compiling
|
|
|
|
@li @ref evas_main_next_steps
|
|
|
|
@li @ref evas_main_intro_example
|
2012-06-13 01:12:36 -07:00
|
|
|
|
|
|
|
|
2012-12-28 15:26:05 -08:00
|
|
|
@section evas_main_intro Introduction
|
2012-06-13 01:12:36 -07:00
|
|
|
|
|
|
|
Evas is a clean display canvas API for several target display systems
|
2017-08-29 16:23:30 -07:00
|
|
|
that can draw anti-aliased text, smooth super- and sub-sampled scaled
|
|
|
|
images, alpha-blend objects and more.
|
|
|
|
|
|
|
|
It abstracts the graphics drawing characteristics of the display
|
|
|
|
system by implementing a canvas where graphical objects can be
|
|
|
|
created, manipulated, and modified. It then handles the rendering
|
|
|
|
pipeline in an optimal way for the underlying device in order to
|
|
|
|
minimize redraws, via a programmatically efficient API.
|
|
|
|
|
|
|
|
A design goal for the system is to run well at both small and large
|
|
|
|
scale, and be portable from embedded systems to multi-CPU
|
|
|
|
workstations. Architecturally, this is achieved via 'backends' that
|
|
|
|
provide the specialized display logic for specific devices. As well,
|
|
|
|
there are various compile options to exclude feature support not
|
|
|
|
required for a target platform to help minimize disk and memory
|
|
|
|
requirements.
|
|
|
|
|
|
|
|
Evas can serve as a base for widget sets or toolkits
|
2020-04-29 07:26:47 -07:00
|
|
|
(e.g. @ref elementary_main) by
|
2017-08-29 16:23:30 -07:00
|
|
|
handling pixel drawing and regional change reporting, but does not
|
|
|
|
manage windows itself, nor deal with input or window update event
|
|
|
|
propagation. In other words, it is intended for use in drawing
|
|
|
|
scrollbars, sliders, and push buttons but not for high-level logic of
|
|
|
|
how the widget operates and behaves. Under Enlightenment, window and
|
|
|
|
widget management is handled by other software components, including
|
|
|
|
@ref Ecore (see @ref Ecore_Evas_Group in particular); however Evas is
|
|
|
|
designed to not be dependent on any particular main loop
|
|
|
|
architecture, and also strives to be input and output system
|
|
|
|
agnostic.
|
2012-06-13 01:12:36 -07:00
|
|
|
|
2017-08-29 16:23:30 -07:00
|
|
|
Evas can be seen as a display system that stands somewhere between a
|
|
|
|
widget set and an immediate mode display system. It retains basic
|
|
|
|
display logic, but does very little high-level logic such as
|
|
|
|
scrollbars, sliders, and push buttons.
|
2012-06-13 01:12:36 -07:00
|
|
|
|
2011-04-08 00:26:20 -07:00
|
|
|
|
2017-08-29 16:23:30 -07:00
|
|
|
@section evas_main_work How does Evas work?
|
2012-06-13 01:12:36 -07:00
|
|
|
|
2017-08-29 16:23:30 -07:00
|
|
|
The Evas canvas is a 'retained mode' renderer, which differs from the
|
|
|
|
more traditional 'immediate mode' display and windowing systems by
|
|
|
|
tracking drawing state information of its contained objects.
|
|
|
|
|
|
|
|
In an immediate mode rendering system, each frame is drawn from
|
|
|
|
scratch by having each drawing element redraw itself. Once the
|
|
|
|
commands are executed, the display system blits the frame to the
|
|
|
|
screen but has no idea how to reproduce the image again, so the
|
|
|
|
application has to run through the same sequence of drawing commands
|
|
|
|
again. Very little or no state is kept from one frame draw to the
|
|
|
|
next; while this is simple it forces each application to manually
|
|
|
|
optimize their graphics code.
|
|
|
|
|
|
|
|
With retained mode systems like Evas, the application does not need
|
|
|
|
to implement the display rendering code and associated logic, but
|
|
|
|
merely updates the list of objects maintained in the canvas. Evas is
|
|
|
|
then able to optimize the processing and rendering of the visible
|
|
|
|
elements, and is better able to avoid redraws due to occlusion or
|
|
|
|
opacity.
|
2012-06-13 01:12:36 -07:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2017-08-29 16:23:30 -07:00
|
|
|
For example, consider the pseudo code:
|
2012-06-13 01:12:36 -07:00
|
|
|
|
|
|
|
@verbatim
|
|
|
|
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;
|
|
|
|
@endverbatim
|
|
|
|
|
2017-08-29 16:23:30 -07:00
|
|
|
By expressing the drawing as a set of drawable objects, Evas is able
|
|
|
|
to internally handle refreshing, updating, moving, resizing, showing,
|
|
|
|
and hiding the objects, and to determine to most efficiently redraw
|
|
|
|
the canvas and its contents to reflect the current state. This
|
|
|
|
permits the application to focus on the higher level logic, which
|
|
|
|
both reduces the amount of coding and allows a more natural way of
|
|
|
|
dealing with the display. Importantly, abstracting the display logic
|
|
|
|
like this also simplifies porting the application to different
|
|
|
|
display systems, since its own code is less tied into how that system
|
|
|
|
works.
|
|
|
|
|
|
|
|
@section evas_main_compiling How to compile the library
|
|
|
|
|
|
|
|
Evas compiles automatically within EFL's build system, and is
|
|
|
|
automatically linked with @ref Ecore and other components that need
|
|
|
|
it. But it can also be built and used standalone, by compiling and
|
|
|
|
linking your application with the compiler flags indicated by @c
|
|
|
|
pkg-config. For example:
|
2012-06-13 01:12:36 -07:00
|
|
|
|
|
|
|
@verbatim
|
2017-08-29 16:23:30 -07:00
|
|
|
gcc -c -o my_main.o my_main.c `pkg-config --cflags evas`
|
2012-06-13 01:12:36 -07:00
|
|
|
|
2017-08-29 16:23:30 -07:00
|
|
|
gcc -o my_application my_main.o `pkg-config --libs evas`
|
2012-06-13 01:12:36 -07:00
|
|
|
@endverbatim
|
|
|
|
|
2012-12-28 15:26:05 -08:00
|
|
|
See @ref pkgconfig
|
2012-06-13 01:12:36 -07:00
|
|
|
|
2017-08-29 16:23:30 -07:00
|
|
|
@section evas_main_next_steps Recommended reading
|
2011-04-08 00:26:20 -07:00
|
|
|
|
2017-08-29 16:23:30 -07:00
|
|
|
@li @ref Ecore, @ref Edje, and @ref Elementary that provide higher
|
|
|
|
level infrastructure and components for real world usage.
|
|
|
|
@li @ref Evas_Object_Group for how to manipulate generic objects on
|
|
|
|
an Evas canvas and handle the associated events.
|
2012-06-13 01:12:36 -07:00
|
|
|
@li @ref Evas_Object_Rectangle, to learn about the most basic object
|
2011-07-06 12:41:31 -07:00
|
|
|
type on Evas -- the rectangle.
|
2012-06-13 01:12:36 -07:00
|
|
|
@li @ref Evas_Object_Polygon, to learn how to create polygon elements
|
2011-08-09 13:56:22 -07:00
|
|
|
on the canvas.
|
docs: Correct the wrong API group name and typo in Evas, Eet, Eina, Eio and Elementary
Summary: I found wrong API reference group name in mapbuf, Evas, Eet, Eina, Eio and fixed them.
Test Plan: API reference documentation modification only
Reviewers: segfaultxavi, stefan_schmidt
Subscribers: cedric, #reviewers, #committers
Tags: #efl
Differential Revision: https://phab.enlightenment.org/D12052
2020-07-14 01:48:04 -07:00
|
|
|
@li @ref Evas_Object_Line_Group, to learn how to create line elements on the
|
2011-08-09 13:56:22 -07:00
|
|
|
canvas.
|
2012-06-13 01:12:36 -07:00
|
|
|
@li @ref Evas_Object_Image, to learn about image objects, over which
|
2011-07-06 12:41:31 -07:00
|
|
|
Evas can do a plethora of operations.
|
docs: Correct the wrong API group name and typo in Evas, Eet, Eina, Eio and Elementary
Summary: I found wrong API reference group name in mapbuf, Evas, Eet, Eina, Eio and fixed them.
Test Plan: API reference documentation modification only
Reviewers: segfaultxavi, stefan_schmidt
Subscribers: cedric, #reviewers, #committers
Tags: #efl
Differential Revision: https://phab.enlightenment.org/D12052
2020-07-14 01:48:04 -07:00
|
|
|
@li @ref Evas_Object_Text_Group, to learn how to create textual elements on
|
2011-07-06 12:41:31 -07:00
|
|
|
the canvas.
|
docs: Correct the wrong API group name and typo in Evas, Eet, Eina, Eio and Elementary
Summary: I found wrong API reference group name in mapbuf, Evas, Eet, Eina, Eio and fixed them.
Test Plan: API reference documentation modification only
Reviewers: segfaultxavi, stefan_schmidt
Subscribers: cedric, #reviewers, #committers
Tags: #efl
Differential Revision: https://phab.enlightenment.org/D12052
2020-07-14 01:48:04 -07:00
|
|
|
@li @ref Evas_Object_Textblock_Group, to learn how to create multiline
|
2011-08-09 13:56:22 -07:00
|
|
|
textual elements on the canvas.
|
2017-08-29 16:23:30 -07:00
|
|
|
|
2012-06-13 01:12:36 -07:00
|
|
|
@li @ref Evas_Smart_Object_Group and @ref Evas_Smart_Group, to define
|
2011-07-06 12:41:31 -07:00
|
|
|
new objects that provide @b custom functions to handle clipping,
|
2017-08-29 16:23:30 -07:00
|
|
|
hiding, moving, resizing, color setting and more. This includes
|
|
|
|
simple grouping of objects that move together (see @ref
|
|
|
|
Evas_Smart_Object_Clipped) and more complex widget-like intelligent
|
|
|
|
behaviors such as buttons and check boxes.
|
2011-04-08 00:26:20 -07:00
|
|
|
|
2012-12-18 08:18:28 -08:00
|
|
|
@section evas_main_intro_example Introductory Example
|
2012-06-13 01:12:36 -07:00
|
|
|
|
|
|
|
@include evas-buffer-simple.c
|
2012-12-28 15:26:05 -08:00
|
|
|
|
|
|
|
More examples can be found at @ref evas_examples.
|
|
|
|
|
2012-06-13 01:12:36 -07:00
|
|
|
*/
|
|
|
|
|
2005-05-21 19:49:50 -07:00
|
|
|
#ifndef _EVAS_H
|
2002-11-08 00:02:15 -08:00
|
|
|
#define _EVAS_H
|
|
|
|
|
2013-04-24 12:56:24 -07:00
|
|
|
#include <Efl_Config.h>
|
|
|
|
|
2009-05-08 14:46:01 -07:00
|
|
|
#include <time.h>
|
|
|
|
|
2009-03-19 23:43:44 -07:00
|
|
|
#include <Eina.h>
|
|
|
|
|
2012-10-08 18:58:41 -07:00
|
|
|
#include <Eo.h>
|
2019-03-07 14:42:01 -08:00
|
|
|
/* This include has been added to support Eo in Evas */
|
2014-08-26 05:52:10 -07:00
|
|
|
#include <Efl.h>
|
2012-10-08 18:58:41 -07:00
|
|
|
|
2013-06-25 00:44:37 -07:00
|
|
|
#include <Evas_Loader.h>
|
|
|
|
|
evas: Rename EAPI macro to EVAS_API in Evas library
Summary:
Patch from a series of patches to rename EAPI symbols to specific
library DSOs.
= The Rationale =
This patch is from a series of patches to rename EAPI symbols to
specific library DSOs.
EAPI was designed to be able to pass
`__attribute__ ((visibility ("default")))` for symbols with
GCC, which would mean that even if -fvisibility=hidden was used
when compiling the library, the needed symbols would get exported.
MSVC __almost__ works like GCC (or mingw) in which you can
declare everything as export and it will just work (slower, but
it will work). But there's a caveat: global variables will not
work the same way for MSVC, but works for mingw and GCC.
For global variables (as opposed to functions), MSVC requires
correct DSO visibility for MSVC: instead of declaring a symbol as
export for everything, you need to declare it as import when
importing from another DSO and export when defining it locally.
With current EAPI definitions, we get the following example
working in mingw and MSVC (observe it doesn't define any global
variables as exported symbols).
Example 1:
dll1:
```
EAPI void foo(void);
EAPI void bar()
{
foo();
}
```
dll2:
```
EAPI void foo()
{
printf ("foo\n");
}
```
This works fine with API defined as __declspec(dllexport) in both
cases and for gcc defining as
`__atttribute__((visibility("default")))`.
However, the following:
Example 2:
dll1:
```
EAPI extern int foo;
EAPI void foobar(void);
EAPI void bar()
{
foo = 5;
foobar();
}
```
dll2:
```
EAPI int foo = 0;
EAPI void foobar()
{
printf ("foo %d\n", foo);
}
```
This will work on mingw but will not work for MSVC. And that's why
LIBAPI is the only solution that works for MSVC.
Co-authored-by: João Paulo Taylor Ienczak Zanette <jpaulotiz@gmail.com>
Co-authored-by: Lucas Cavalcante de Sousa <lucks.sousa@gmail.com>
Co-authored-by: Ricardo Campos <ricardo.campos@expertise.dev>
Reviewers: vtorri, woohyun, jptiz, lucas
Reviewed By: vtorri, lucas
Subscribers: cedric, #reviewers, #committers
Tags: #efl
Differential Revision: https://phab.enlightenment.org/D12214
2020-12-15 18:02:20 -08:00
|
|
|
#include <evas_api.h>
|
2009-03-19 23:43:44 -07:00
|
|
|
|
2010-05-28 23:37:19 -07:00
|
|
|
#ifdef __cplusplus
|
|
|
|
extern "C" {
|
|
|
|
#endif
|
|
|
|
|
2019-03-07 15:40:20 -08:00
|
|
|
#include <interfaces/efl_gfx_types.eot.h>
|
|
|
|
#include <interfaces/efl_gfx_path.eo.h>
|
|
|
|
#include <interfaces/efl_text_types.eot.h>
|
2019-10-31 12:43:16 -07:00
|
|
|
#include <canvas/efl_input_types.eot.h>
|
2013-06-20 03:53:29 -07:00
|
|
|
#include <Evas_Common.h>
|
2019-03-07 15:40:20 -08:00
|
|
|
|
2013-04-24 12:56:24 -07:00
|
|
|
#ifndef EFL_NOLEGACY_API_SUPPORT
|
|
|
|
#include <Evas_Legacy.h>
|
|
|
|
#endif
|
2019-03-07 14:42:01 -08:00
|
|
|
#ifdef EFL_BETA_API_SUPPORT
|
2013-04-24 12:56:24 -07:00
|
|
|
#include <Evas_Eo.h>
|
2019-03-07 14:42:01 -08:00
|
|
|
#endif
|
2015-04-28 05:24:11 -07:00
|
|
|
|
2002-11-08 00:02:15 -08:00
|
|
|
#ifdef __cplusplus
|
|
|
|
}
|
|
|
|
#endif
|
|
|
|
|
|
|
|
#endif
|