enlightenment/efl
enlightenment
/
efl
8
7
Fork 14
Code Issues 13 Pull Requests 1 Projects Releases Wiki Activity

[evas] Just explaining more the main top function blocks the 

main doc. page points to.
The rest is just a proof read check on the main section.



SVN revision: 61098
This commit is contained in:
Gustavo Lima Chaves 2011-07-06 19:41:31 +00:00
parent 32d38b1a61
commit 153c7394df
1 changed files with 100 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

188
legacy/evas/src/lib/Evas.h
View File

@ -45,25 +45,26 @@
@section intro What is Evas? @section intro What is Evas?
Evas is a clean display canvas API for several target display systems that Evas is a clean display canvas API for several target display systems
can draw anti-aliased text, smooth super and sub-sampled scaled images, that can draw anti-aliased text, smooth super and sub-sampled scaled
alpha-blend objects much and more. images, alpha-blend objects and much more.
It abstracts any need to know much about what the characteristics of your It abstracts any need to know much about what the characteristics of
display system are or what graphics calls are used to draw them and how. It your display system are or what graphics calls are used to draw them
deals on an object level where all you do is create and manipulate objects and how. It deals on an object level where all you do is create and
in a canvas, set their properties, and the rest is done for you. manipulate objects in a canvas, set their properties, and the rest is
done for you.
Evas optimises the rendering pipeline to minimise effort in redrawing changes Evas optimises the rendering pipeline to minimise effort in redrawing
made to the canvas and so takes this work out of the programmers hand, changes made to the canvas and so takes this work out of the
saving a lot of time and energy. programmers hand, saving a lot of time and energy.
It's small and lean, designed to work on embedded systems all the way to It's small and lean, designed to work on embedded systems all the way
large and powerful multi-cpu workstations. It can be compiled to only have to large and powerful multi-cpu workstations. It can be compiled to
the features you need for your target platform if you so wish, thus keeping only have the features you need for your target platform if you so
it small and lean. It has several display back-ends, letting it display on wish, thus keeping it small and lean. It has several display
several display systems, making it portable for cross-device and back-ends, letting it display on several display systems, making it
cross-platform development. portable for cross-device and cross-platform development.
@subsection intro_not_evas What Evas is not? @subsection intro_not_evas What Evas is not?
@ -73,7 +74,7 @@ for a toolkit based on Evas, Edje, Ecore and other Enlightenment
technologies. technologies.
It is not dependent or aware of main loops, input or output It is not dependent or aware of main loops, input or output
systems. Input should be polled from various sources and feed them to systems. Input should be polled from various sources and fed to
Evas. Similarly, it will not create windows or report windows updates Evas. Similarly, it will not create windows or report windows updates
to your system, rather just drawing the pixels and reporting to the to your system, rather just drawing the pixels and reporting to the
user the areas that were changed. Of course these operations are quite user the areas that were changed. Of course these operations are quite
@ -84,14 +85,15 @@ Ecore_Evas (http://docs.enlightenment.org/auto/ecore/).
@section work How does Evas work? @section work How does Evas work?
Evas is a canvas display library. This is markedly different from most Evas is a canvas display library. This is markedly different from most
display and windowing systems as a Canvas is structural and is also a state display and windowing systems as a canvas is structural and is also a
engine, whereas most display and windowing systems are immediate mode display state engine, whereas most display and windowing systems are immediate
targets. Evas handles the logic between a structural display via its' state mode display targets. Evas handles the logic between a structural
engine, and controls the target windowing system in order to produce display via its state engine, and controls the target windowing system
rendered results of the current canvases state on the display. 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 Immediate mode display systems retain very little, or no state. A
will execute a series of commands, as in the pseudo code: program will execute a series of commands, as in the pseudo code:
@verbatim @verbatim
draw line from position (0, 0) to position (100, 200); draw line from position (0, 0) to position (100, 200);
@ -103,27 +105,29 @@ scale bitmap_handle to size 100 x 100;
draw image bitmap_handle at position (10, 30); draw image bitmap_handle at position (10, 30);
@endverbatim @endverbatim
The series of commands is executed by the windowing system and the results The series of commands is executed by the windowing system and the
are displayed on the screen (normally). Once the commands are executed the results are displayed on the screen (normally). Once the commands are
display system has little or no idea of how to reproduce this image again, executed the display system has little or no idea of how to reproduce
and so has to be instructed by the application how to redraw sections of the this image again, and so has to be instructed by the application how
screen whenever needed. Each successive command will be executed as to redraw sections of the screen whenever needed. Each successive
instructed by the application and either emulated by software or sent to the command will be executed as instructed by the application and either
graphics hardware on the device to be performed. 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 The advantage of such a system is that it is simple, and gives a
tight control over how something looks and is drawn. Given the increasing program tight control over how something looks and is drawn. Given the
complexity of displays and demands by users to have better looking increasing complexity of displays and demands by users to have better
interfaces, more and more work is needing to be done at this level by the looking interfaces, more and more work is needing to be done at this
internals of widget sets, custom display widgets and other programs. This level by the internals of widget sets, custom display widgets and
means more and more logic and display rendering code needs to be written other programs. This means more and more logic and display rendering
time and time again, each time the application needs to figure out how to code needs to be written time and time again, each time the
minimise redraws so that display is fast and interactive, and keep track of application needs to figure out how to minimise redraws so that
redraw logic. The power comes at a high-price, lots of extra code and work. display is fast and interactive, and keep track of redraw logic. The
Programmers not very familiar with graphics programming will often make power comes at a high-price, lots of extra code and work. Programmers
mistakes at this level and produce code that is sub optimal. Those familiar not very familiar with graphics programming will often make mistakes
with this kind of programming will simply get bored by writing the same code at this level and produce code that is sub optimal. Those familiar
again and again. with this kind of programming will simply get bored by writing the
same code again and again.
For example, if in the above scene, the windowing system requires the For example, if in the above scene, the windowing system requires the
application to redraw the area from 0, 0 to 50, 50 (also referred as application to redraw the area from 0, 0 to 50, 50 (also referred as
@ -149,7 +153,7 @@ Redraw from position (0, 0) to position (50, 50):
The clever reader might have noticed that, if all elements in the The clever reader might have noticed that, if all elements in the
above scene are opaque, then the system is doing useless paints: part above scene are opaque, then the system is doing useless paints: part
of the line is behind the rectangle, and part of the rectangle is of the line is behind the rectangle, and part of the rectangle is
behind the image. These useless paints tends to be very costly, as behind the image. These useless paints tend to be very costly, as
pixels tend to be 4 bytes in size, thus an overlapping region of 100 x pixels tend to be 4 bytes in size, thus an overlapping region of 100 x
100 pixels is around 40000 useless writes! The developer could write 100 pixels is around 40000 useless writes! The developer could write
code to calculate the overlapping areas and avoid painting then, but code to calculate the overlapping areas and avoid painting then, but
@ -157,10 +161,10 @@ then it should be mixed with the "expose event" handling mentioned
above and quickly one realizes the initially simpler method became above and quickly one realizes the initially simpler method became
really complex. really complex.
Evas is a structural system in which the programmer creates and manages Evas is a structural system in which the programmer creates and
display objects and their properties, and as a result of this higher level manages display objects and their properties, and as a result of this
state management, the canvas is able to redraw the set of objects when higher level state management, the canvas is able to redraw the set of
needed to represent the current state of the canvas. objects when needed to represent the current state of the canvas.
For example, the pseudo code: For example, the pseudo code:
@ -182,32 +186,34 @@ show bitmap_handle;
render scene; render scene;
@endverbatim @endverbatim
This may look longer, but when the display needs to be refreshed or updated, This may look longer, but when the display needs to be refreshed or
the programmer only moves, resizes, shows, hides etc. the objects that they updated, the programmer only moves, resizes, shows, hides etc. the
need to change. The programmer simply thinks at the object logic level, and objects that need to change. The programmer simply thinks at the
the canvas software does the rest of the work for them, figuring out what object logic level, and the canvas software does the rest of the work
actually changed in the canvas since it was last drawn, how to most for them, figuring out what actually changed in the canvas since it
efficiently redraw he canvas and its contents to reflect the current state, was last drawn, how to most efficiently redraw the canvas and its
and then it can go off and do the actual drawing of the canvas. contents to reflect the current state, and then it can go off and do
the actual drawing of the canvas.
This lets the programmer think in a more natural way when dealing with a This lets the programmer think in a more natural way when dealing with
display, and saves time and effort of working out how to load and display a display, and saves time and effort of working out how to load and
images, render given the current display system etc. Since Evas also is display images, render given the current display system etc. Since
portable across different display systems, this also gives the programmer Evas also is portable across different display systems, this also
the ability to have their code ported and display on different display gives the programmer the ability to have their code ported and
systems with very little work. displayed on different display systems with very little work.
Evas can be seen as a display system that stands somewhere between a widget Evas can be seen as a display system that stands somewhere between a
set and an immediate mode display system. It retains basic display logic, widget set and an immediate mode display system. It retains basic
but does very little high-level logic such as scrollbars, sliders, push display logic, but does very little high-level logic such as
buttons etc. scrollbars, sliders, push buttons etc.
@section compiling How to compile using Evas ? @section compiling How to compile using Evas ?
Evas is a library your application links to. The procedure for this is very Evas is a library your application links to. The procedure for this is
simple. You simply have to compile your application with the appropriate very simple. You simply have to compile your application with the
compiler flags that the @p pkg-config script outputs. For example: appropriate compiler flags that the @c pkg-config script outputs. For
example:
Compiling C or C++ files into object files: Compiling C or C++ files into object files:
@ -221,18 +227,19 @@ Linking object files into a binary executable:
gcc -o my_application main.o `pkg-config --libs evas` gcc -o my_application main.o `pkg-config --libs evas`
@endverbatim @endverbatim
You simply have to make sure that pkg-config is in your shell's PATH (see You simply have to make sure that @c pkg-config is in your shell's @c
the manual page for your appropriate shell) and evas.pc in /usr/lib/pkgconfig PATH (see the manual page for your appropriate shell) and @c evas.pc
or its path is in the PKG_CONFIG_PATH environment variable. It's that simple in @c /usr/lib/pkgconfig or its path in the @c PKG_CONFIG_PATH
to link and use Evas once you have written your code to use it. environment variable. It's that simple to link and use Evas once you
have written your code to use it.
Since the program is linked to Evas, it is now able to use any advertised Since the program is linked to Evas, it is now able to use any
API calls to display graphics in a canvas managed by Evas, as well as use advertised API calls to display graphics in a canvas managed by it, as
the API calls provided to manage data as well. well as use the API calls provided to manage data.
You should make sure you add any extra compile and link flags to your You should make sure you add any extra compile and link flags to your
compile commands that your application may need as well. The above example compile commands that your application may need as well. The above
is only guaranteed to make Evas add it's own requirements. example is only guaranteed to make Evas add it's own requirements.
@section install How is it installed? @section install How is it installed?
@ -259,17 +266,22 @@ you tons of work compared to using just Evas directly.
Recommended reading: Recommended reading:
@li @ref Evas_Object_Group @li @ref Evas_Object_Group, where you'll get how to basically
@li @ref Evas_Object_Rectangle manipulate generic objects lying on an Evas canvas, handle canvas
@li @ref Evas_Object_Image and object events, etc.
@li @ref Evas_Object_Text @li @ref Evas_Object_Rectangle, to learn about the most basic object
@li @ref Evas_Smart_Object_Group and @ref Evas_Smart_Group to define type on Evas -- the rectangle.
an object that provides custom functions to handle clipping, @li @ref Evas_Object_Image, to learn about image objects, over which
hiding, moving, resizing, setting the color and more. These could Evas can do a plethora of operations.
@li @ref Evas_Object_Text, to learn how to create textual elements on
the canvas.
@li @ref Evas_Smart_Object_Group and @ref Evas_Smart_Group, to define
new objects that provide @b custom functions to handle clipping,
hiding, moving, resizing, color setting and more. These could
be as simple as a group of objects that move together (see @ref be as simple as a group of objects that move together (see @ref
Evas_Smart_Object_Clipped). These smart objects can implement what Evas_Smart_Object_Clipped) up to implementations of what
ends to be a widget, providing some intelligence (thus the name), ends to be a widget, providing some intelligence (thus the name)
like a button or check box. to Evas objects -- like a button or check box, for example.
@section intro_example Introductory Example @section intro_example Introductory Example