Python-EFL: put in the infra for Evas docs
SVN revision: 84337
This commit is contained in:
parent
ca6be7473c
commit
83b3d779cb
2
TODO
2
TODO
|
|
@ -20,7 +20,6 @@ TODO:
|
|||
* include python-ethumb
|
||||
* include python-e_dbus (or make edbus2 ??)
|
||||
* check emotion api completness
|
||||
* elm.Label Slide Mode
|
||||
* elm.Notify align_set/get/prop
|
||||
* cleanup elementary_object
|
||||
|
||||
|
|
@ -46,6 +45,5 @@ CHANGES FROM 1.7 to 1.8:
|
|||
* elementary.need_e_dbus => elementary.need_e_dbus
|
||||
* elm.domain_translatable_text_part_set => elm.domain_translatable_part_text_set
|
||||
* elm.Scroller.custom_widget_base_theme_set => elm.Layout.theme_set TODO is this right?
|
||||
* elm.Label.slide_set/get/prop removed => Slide Mode (TODO)
|
||||
* elm.notify.orient_set/get/prop removed => align_set (TODO)
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ efl Package
|
|||
|
||||
.. toctree::
|
||||
|
||||
module-evas
|
||||
evas/evas
|
||||
module-ecore
|
||||
module-emotion
|
||||
elementary/elementary
|
||||
|
|
|
|||
|
|
@ -0,0 +1,5 @@
|
|||
:class:`efl.evas.Canvas` Class
|
||||
===============================
|
||||
|
||||
.. autoclass:: efl.evas.Canvas
|
||||
:inherited-members:
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
:class:`efl.evas.Box` Class
|
||||
===============================
|
||||
|
||||
.. autoclass:: efl.evas.Box
|
||||
:inherited-members:
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
:class:`efl.evas.Image` Class
|
||||
===============================
|
||||
|
||||
.. autoclass:: efl.evas.Image
|
||||
:inherited-members:
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
:class:`efl.evas.Line` Class
|
||||
===============================
|
||||
|
||||
.. autoclass:: efl.evas.Line
|
||||
:inherited-members:
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
:class:`efl.evas.Polygon` Class
|
||||
===============================
|
||||
|
||||
.. autoclass:: efl.evas.Polygon
|
||||
:inherited-members:
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
:class:`efl.evas.Rectangle` Class
|
||||
===============================
|
||||
|
||||
.. autoclass:: efl.evas.Rectangle
|
||||
:inherited-members:
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
:class:`efl.evas.SmartObject` Class
|
||||
===============================
|
||||
|
||||
.. autoclass:: efl.evas.SmartObject
|
||||
:inherited-members:
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
:class:`efl.evas.Text` Class
|
||||
===============================
|
||||
|
||||
.. autoclass:: efl.evas.Text
|
||||
:inherited-members:
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
:class:`efl.evas.Textblock` Class
|
||||
===============================
|
||||
|
||||
.. autoclass:: efl.evas.Textblock
|
||||
:inherited-members:
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
:class:`efl.evas.Object` Class
|
||||
===============================
|
||||
|
||||
.. autoclass:: efl.evas.Object
|
||||
:inherited-members:
|
||||
|
|
@ -0,0 +1,217 @@
|
|||
:mod:`efl.evas` Module
|
||||
======================
|
||||
|
||||
|
||||
What is Evas?
|
||||
-------------
|
||||
|
||||
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 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.
|
||||
|
||||
Evas optimises the rendering pipeline to minimise 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's small and lean, 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, thus keeping it small and lean. It has several display
|
||||
back-ends, letting it display on several display systems, making it
|
||||
portable for cross-device and cross-platform development.
|
||||
|
||||
|
||||
What Evas is not?
|
||||
-----------------
|
||||
|
||||
Evas is not a widget set or widget toolkit, however it is their base. See
|
||||
:doc:`Elementary </elementary/elementary>` for a toolkit
|
||||
based on :doc:`Evas </evas/evas>`, :doc:`Edje </edje/edje>`,
|
||||
:doc:`Ecore </ecore/ecore>` and other Enlightenment technologies.
|
||||
|
||||
It is not dependent or aware of main loops, input or output systems. Input
|
||||
should be polled from various sources and fed to Evas. Similarly, it will
|
||||
not create windows or report windows updates to your system, rather just
|
||||
drawing the pixels and reporting to the user the areas that were changed.
|
||||
|
||||
|
||||
How does Evas work?
|
||||
-------------------
|
||||
|
||||
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 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 will execute a series of commands, as in the 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 displayed on the screen (normally). Once the commands are
|
||||
executed the display system has little or no idea of how to reproduce
|
||||
this image again, and so has to be instructed by the application how
|
||||
to redraw sections of the screen whenever needed. Each successive
|
||||
command will be 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 and more work is needing to be done at this
|
||||
level by the internals of widget sets, custom display widgets and
|
||||
other programs. This means more and more logic and display rendering
|
||||
code needs to be written time and time again, each time the
|
||||
application needs to figure out how to minimise redraws so that
|
||||
display is fast and interactive, and keep track of redraw logic. The
|
||||
power comes at a high-price, lots of extra code and work. Programmers
|
||||
not very familiar with graphics programming will often make mistakes
|
||||
at this level and produce code that is sub optimal. Those familiar
|
||||
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
|
||||
application to redraw the area from 0, 0 to 50, 50 (also referred as
|
||||
"expose event"), then the programmer must calculate manually the
|
||||
updates and repaint 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);
|
||||
|
||||
The clever reader might have noticed that, if all elements in the
|
||||
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
|
||||
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
|
||||
100 pixels is around 40000 useless writes! The developer could write
|
||||
code to calculate the overlapping areas and avoid painting then, but
|
||||
then it should be mixed with the "expose event" handling mentioned
|
||||
above and quickly one realizes the initially simpler method became
|
||||
really complex.
|
||||
|
||||
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, the 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 may look 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 simply thinks at the
|
||||
object logic level, and the canvas software does the rest of the work
|
||||
for them, figuring out what actually 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 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 display, and saves time and effort of working out how to load and
|
||||
display images, render given the current display system etc. Since
|
||||
Evas also is portable across different display systems, this also
|
||||
gives the programmer the ability to have their code ported and
|
||||
displayed on different display systems with very little work.
|
||||
|
||||
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, push buttons etc.
|
||||
|
||||
|
||||
Next Steps
|
||||
----------
|
||||
|
||||
After you understood what Evas is and installed it in your system you
|
||||
should proceed understanding the programming interface for all
|
||||
objects, then see the specific for the most used elements. We'd
|
||||
recommend you to take a while to learn
|
||||
:doc:`Elementary </elementary/elementary>` and :doc:`Edje </edje/edje>` as
|
||||
they will likely save you tons of work compared to using just Evas directly.
|
||||
|
||||
Recommended reading:
|
||||
|
||||
- :class:`efl.evas.Canvas`, where you'll get how to handle an Evas canvas,
|
||||
- :class:`efl.evas.Object`, where you'll get how to basically manipulate generic
|
||||
objects lying on an Evas canvas, handle canvas and object events, etc.
|
||||
- :class:`efl.evas.Rectangle`, to learn about the most basic object type on Evas --
|
||||
the rectangle.
|
||||
- :class:`efl.evas.Polygon`, to learn how to create polygon elements on the canvas.
|
||||
- :class:`efl.evas.Line`, to learn how to create line elements on the canvas.
|
||||
- :class:`efl.evas.Image`, to learn about image objects, over which Evas can do a
|
||||
plethora of operations.
|
||||
- :class:`efl.evas.Text`, to learn how to create textual elements on the canvas.
|
||||
- :class:`efl.evas.Textblock`, to learn how to create multiline textual elements on
|
||||
the canvas.
|
||||
- :class:`efl.evas.Box`, to learn how to pack objects in different layouts.
|
||||
- :class:`efl.evas.SmartObject`, to define new objects that provide *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 :class:`efl.evas.ClippedSmartObject`) up to
|
||||
implementations of what ends to be a widget, providing some
|
||||
intelligence (thus the name) to Evas objects -- like a button or
|
||||
check box, for example.
|
||||
|
||||
|
||||
Reference
|
||||
---------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 4
|
||||
|
||||
class-canvas
|
||||
class-object
|
||||
class-object-rectangle
|
||||
class-object-image
|
||||
class-object-line
|
||||
class-object-polygon
|
||||
class-object-text
|
||||
class-object-textblock
|
||||
class-object-box
|
||||
class-object-smart
|
||||
|
||||
|
||||
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
:mod:`efl.evas` Module
|
||||
----------------------
|
||||
|
||||
.. automodule:: efl.evas
|
||||
|
|
@ -167,10 +167,27 @@ def shutdown():
|
|||
|
||||
|
||||
def render_method_lookup(name):
|
||||
"""render_method_lookup(name)
|
||||
|
||||
Lookup render method and return its id (> 0 if found).
|
||||
|
||||
@param name: Render method
|
||||
@type name: string
|
||||
@return: ID
|
||||
@rtype: int
|
||||
|
||||
"""
|
||||
return evas_render_method_lookup(_cfruni(name))
|
||||
|
||||
|
||||
def render_method_list():
|
||||
"""render_method_list()
|
||||
|
||||
Returns a list of render method names.
|
||||
|
||||
@rtype: list of str
|
||||
|
||||
"""
|
||||
cdef Eina_List *lst
|
||||
|
||||
ret = []
|
||||
|
|
|
|||
|
|
@ -105,7 +105,73 @@ cdef _object_del_callback_from_list(Object obj, int type, func):
|
|||
|
||||
|
||||
cdef class Object(Eo):
|
||||
"""Basic Graphical Object (or actor).
|
||||
|
||||
Objects are managed by L{Canvas} in a non-immediate way, that is,
|
||||
all operations, like moving, resizing, changing the color, etc will
|
||||
not trigger immediate repainting, instead it will save the new state
|
||||
and mark both this object and its Canvas as "dirty" so can be redrawn
|
||||
on L{Canvas.render()} (usually called by the underlying system, like
|
||||
B{ecore.evas} when you're entering idle. This means that doesn't matter
|
||||
how many times you're moving an object between frame updates: just the
|
||||
last state will be used, that's why you really should do animations
|
||||
using L{ecore.animator_add()} instead of L{ecore.timer_add()}, since
|
||||
it will call registered functions in one batch and then trigger redraw,
|
||||
instead of calling one function, then redraw, then the next function,
|
||||
and redraw...
|
||||
|
||||
The most important concept for evas object is B{clipping}
|
||||
(L{clip_set()} and L{clip_unset()}), usually done by use of
|
||||
L{Rectangle} as clipper. Clip objects will affect the drawing behavior:
|
||||
- Limiting visibility
|
||||
- Limiting geometry
|
||||
- Modulating color
|
||||
Clips respects the hierarchy: the minimum area and the composed color
|
||||
will be used used at the end, if one object is not visible, othe lower
|
||||
objects (clipped by it) will not be visible as well. Clipping is the
|
||||
recommended way of doing fade out/in effect, instead of changing object's
|
||||
color, clip it to a rectangle and change its color: this will work as
|
||||
expected with every object, unlike directly changing color that just
|
||||
work for L{Image}s.
|
||||
|
||||
As with every evas component, colors should be specified in
|
||||
B{pre-multiplied} format, see L{evas.color_parse()} and
|
||||
L{evas.color_argb_premul()}.
|
||||
|
||||
Objects can be grouped by means of L{SmartObject}, a virtual class
|
||||
that can have it's methods implemented in order to apply methods to
|
||||
its children.
|
||||
|
||||
@attention: since we have two systems controlling object's life (Evas
|
||||
and Python) objects need to be explicitly deleted using L{delete()}
|
||||
call. If this call is not issued, the Python object will not be
|
||||
released, but if the object is deleted by Evas (ie: due parent
|
||||
deletion), the object will become "shallow" and all operations
|
||||
will either have no effect or raise exceptions. You can be notified
|
||||
of object deletion by the C{EVAS_CALLBACK_FREE} (see L{on_free_add()}
|
||||
or L{event_callback_add()}.
|
||||
|
||||
@ivar data: utility dict used to hold any user data.
|
||||
@ivar evas: L{Canvas} that owns this object.
|
||||
|
||||
@group State manipulation: clip_set, clip_get, clip_unset, clip,
|
||||
color_set, color_get, color, show, hide, visible_set, visible_get,
|
||||
visible, delete, is_deleted
|
||||
@group Positioning: pos_set, pos_get, pos, move, move_relative,
|
||||
size_set, size_get, size, resize, geometry*, center*, top_left*,
|
||||
top_right*, bottom_left*, bottom_right*
|
||||
@group Layer & Stack manipulation: above_get, above, below_get, below,
|
||||
layer_set, layer_get, layer, lower, raise_, stack_above, stack_below,
|
||||
bottom_get, bottom, top_get, top
|
||||
@group Event processing control: focus_set, focus_get, focus,
|
||||
pass_events*, repeat_events*, propagate_events*
|
||||
@group Event callbacks: event_callback_*, on_*
|
||||
@group Often unused: render_op*, anti_alias*, pointer_mode*
|
||||
|
||||
@param evas: Evas canvas for this object
|
||||
@type evas: L{Canvas}
|
||||
|
||||
"""
|
||||
def __cinit__(self):
|
||||
self._callbacks = [None] * evas_object_event_callbacks_len
|
||||
|
||||
|
|
@ -158,6 +224,11 @@ cdef class Object(Eo):
|
|||
self.name_set(name)
|
||||
|
||||
def delete(self):
|
||||
"""delete()
|
||||
|
||||
Delete the evas object.
|
||||
|
||||
"""
|
||||
evas_object_del(self.obj)
|
||||
|
||||
def evas_get(self):
|
||||
|
|
|
|||
Loading…
Reference in New Issue