E17 library tutorial
News: Updated for Evas2 / Evas 1.0.0_pre-whatever. See Enlightenment
for CVS info.
Welcome to the E17 libs sample collection!
I wanted to learn a little about Imlib2, Evas and Ecore from E17, so I spent some time with the source and wrote a few simple test programs.
They start with a simple Imlib2 program and move on to use Ecore and Evas.
Each one only includes a few changes so you can see what's needed for a specific feature.
So let's get to the code. Grab the
How do I build?
You'll need the E17 libraries installed.
If you've got E17 from CVS running, then you should be all set.
The sample programs have a very simple Makefile in each directory.
Enter a directory and type 'make'.
You should get an executable.
If you have a non-standard include or library install you'll need to modify the Makefiles.
This web page, including images.
Directories: /fnt /img
Common files used by the samples. These come from evas_test.
If you are experimenting look in the E17 build tree
at e17/libs/evas/data for additional fonts and images to try.
Directories: /x1 /x2 /x3 ... /x_poly1 ...
Each directory contains a sample. The code is in 'x.c'.
A 'Makefile' is included. After a 'make', you should get an application named 'x'.
Run it in the same directory and you'll get a small window.
Most samples can be closed by clicking on the background, all can be closed by using your window manager's close button.
First sample. Goal: Create a window using Xlib, use Imlib2 to display an icon.
Secondary goals: Make the application update the icon if overlapped by another window and uncovered.
Close the application if a click event occurs within the window.
Demonstrates basic X11 window creation, using only Xlib.
Shows how to initialize Imlib2 so it can draw to the window.
Shows basic Xlib event handling.
Let's check out Ecore. x1 is a basic X application, let's see what we can simplify by using Ecore in place of some Xlib calls.
The source contains a bunch of '#if 0's around sections of Xlib code replaced with Ecore calls.
Functionally, x2 and x1 work the same (and look visually the same), only the support libraries have changed.
Ecore items covered:
- Open display
- Create window
- Select events (tell X what we want to be notified of)
- Map window (display it)
- Event loop helpers
x3 - finally Evas!
Moving on to Evas, x3 adds an Evas canvas to the sample application.
Working with x2, we're going to convert it to an Evas application.
The Evas replaces Imlib2 functionality, so you'll find we can do without a bunch of the Imlib2 setup calls.
Additionally, Evas now tracks our screen objects for us (icons, rectangles, text, etc...) so we won't be required to update (repaint/redraw) our objects on every Expose event from X. (I've oversimplified this...)
Evas also handles layering for us, so we just tell Evas what's on top, what's on the bottom, and how transparent any of our objects are.
x3 still doesn't do anything new, but it does include simplified window updating for expose events and conversion to Evas. Next... some fun!
x4 - A little animation
Back to Ecore again. Let's simplify our event handling a little.
Ecore supports calling event callback functions when an event is sent from X.
This lets us install event handlers (callbacks) and leave Ecore to handle the event loop.
Ecore will also handle calling an idle handler.
That will handle the rendering we need to let Evas do while we aren't responding to X events.
Note that I've left event_loop() in the source, but it isn't used.
e_event_loop() is called instead, and since we previously installed a few event handlers (with e_event_filter_handler_add()) Ecore will take care of calling our functions when X events are received.
This application also introduces Ecore timers.
We add a timer to animate the icon across our canvas.
When the timer expires we move our icon by telling Evas to move it.
Animation is really easy with Evas, all you need to do is keep the Evas_Object handle available, then tell Evas where to move the object.
Layering and transparency work the same way...
Nothing new here. Clean up the code, removing unused parts.
Adjust animation timing.
x6 - transparency
Let's play with some more Evas features now.
I've added another icon, and we're going to vary the transparency of the Evas icon during the animation.
We also get to layer the objects, so watch which one appears on top of the other.
You'll find an extra Evas rect in the code, but notice it isn't being displayed.
It's there because initally I was hiding the Evas icon behind a transparent rect. to fade it.
Then I discovered that evas_set_color() works like a filter on image objects.
Set the color to all white (255,255,255) and you can vary the transparency.
You can also vary the color, for example (255,0,0) in the color parameters will show only red, filtering out all green and blue.
Oh, and use the Ecore helper to set a window title...
x7 - text
Add an Evas text object.
Use Evas functions to get size of the text so we can place it along the lower window edge.
Also add Evas object callbacks so we can indicate when the mouse moves over the text, and a mouse up callback so the text can behave like a button.
Note that we still need to use the Ecore functions to enable events and Ecore event filtering callbacks to pass the events to Evas.
Then Evas lets us install callbacks for any object we want.
I've broken the mouse handling slightly here.
Now you'll find the background clicks no longer close the application.
We'll fix that next.
It's caused by passing all the mouse clicks events to Evas, so they can no longer be caught by our standard Ecore callback.
Let's make the text behave more like a button.
Add a shadow, and animate the text so it moves down to the shadow if pushed.
Fix application closing by adding a Evas object callback for the background rect, so clicking will close the app. again.
We can share the mouse_up callback by checking which Evas object was 'hit' within the callback.
Or we could install a second callback, so that each gets called only for one object.
I've chosen the former.
Polygons. Evas polygon sample, with two poly objects.
Polys in Evas are auto-closing, so just supply three points for a triangle and the object will be filled automatically.
One caveat, the event detection for a poly object covers the bounding rectangle of the poly.
For example, click on the right triangle.
You'll get a msg of 'mouse_down:poly_r'.
Now click in the right corner of the rectangle containing poly_r, outside the shaded area.
You'll see another mouse down for the poly.
I've added a second poly object to give you a sample of stacking within Evas layers.
Within a layer, Evas objects are stacked as shown (or as created?, I haven't tested which of these is true) bottom to top.
So, since I show the right poly first, followed by the left poly, you'll see that clicking in the region between the polys generates a mouse down event for left poly with that rectangle, otherwise it generates a right poly mouse down.
Here's a really quick sample with resize and key events.
The event changes use Ecore in this sample.
There are also some lines to hilight the event region the polygon will respond to.
Key events are printed to the console when they occur, but you'll see how to get them from the key_down_cb() function.
Of course you also have to tell Ecore you want X to send them to you...
There's code included to change the resize behavior.
By default, the window resize will scale the contents with the window size.
If you change the #if in config_cb() you'll get a window resize with the objects at fixed size.
If you haven't found them yet, you'll want to be looking at Evas.h and Ecore.h for prototypes for all the functions.
Plus Ecore.h has useful info like helpful X event defines and Ecore event types.
You'll usually find these files in /usr/local/include.
You can also find them in the CVS distro at e17/libs/evas/src/lib/Evas.h and e17/libs/ecore/src/Ecore.h.
Test apps are your friend
You can also find examples of Evas use in the test apps.
Check e17/libs/evas/src/bin and read the source for some examples.
For use of Ecore, you may have to look at E itself (e17/apps/e/src) or read the Ecore source to see what it does.
You'll probably find some of the X man pages useful.
XEvent is handy, and includes a general list of events.
If you see an Ecore or E17 call to Xlib, you should find a man page for the call, assuming you've included X man pages in your system install.
My system: These samples were built successfully on a SuSE 8.1 system, running kernel 2.5.67 and XFree86 4.3.0.
Version 0.10 was built against E17 CVS from Mar 2003.
Usual disclaimers apply... This is development code. While I've tested it on my system I make no claims for your particular setup. This is released under the license applied to Enlightenment. Please report problems you find so I can update the source!