Page MenuHomePhabricator

An Artist's Approach to Edje
Updated 3,371 Days AgoPublic

1. Introduction

1.1 What is it?

Edje is a programming library that separates the appearance of a program from the code that defines the rationale behind the work.
In this way, the programmer does not have to mess with the appearance of the program and transfers the entire process of planning the graphical part of the application back to the designers in order to create applications with improved aesthetics and functionality.

In addition to creating "classic" graphic items such as buttons, toolbars, containers etc. Edje allows the discerning designer to appoint his own widgets that will work and will appear as the designer wants. Particularly important are the effects that one can create, which range from simple effects using series of frames, to complex ones affected by various events (eg by interacting with the user's clicking or according to how the state of other UI parts change, etc).

{F2414, size=full}

1.2 Edje and the Layouts

Graphical "themes" created for Edje are saved in files with .edj suffix.
These files contain both the UI description and all the data files needed (images, fonts etc) for the theme to be displayed properly. In addition an edj file contains multiple collections and layouts giving you the ability to create UI sets that support all kinds of devices (eg. Desktops, Netbooks, Smartphones) as well as any special screen orientations they might have (eg. horizontal orientation in smartphones) and all of these packed up nicely in a single file for easier deployment.

1.3 Edje Data Collections

The edj files we mentioned in section 1.2 are the files that can be read by applications using Edje but not the ones created by designers themselves. In fact, designers create UI descriptions in files with .edc suffix (Edje Data Collections) that are compiled in .edj files by a program called edje_cc
This is happening so all the files can be bundled up in a single file that can be read fast by the application that needs it.

Every edc file has 3 basic sections: the images, the data and the collections.

On the image section, we basically have a list of all the images we want available in our UI.
They are also the images that are going to be included in our final edj file.
We also define the image compression level we want for the enlisted images in this section.

On the data section (which is optional) we can have data in key-value form that we want the application that uses our theme to have access to.

Finally, the collections section is the place with the actual UI description, in other words how our UI looks like and how it interacts with the application and the user.

1.4 Even more Edje Data Collections

As we mentioned earlier, the actual description of our UI lives inside the collections section of our edc file. Because there was a need for even more complex graphical elements a groups section was created.
Thus one of the basic building blocks of the collections are the group elements, which of course can be used multiple times inside a collections block.

Parts are also fundamental elements of a UI (text, rectangle and images are parts) and they can be described by one or more states (as we'll see in the examples of chapter 2).
For example you can have a starting/default state of a part that describes its appearance when idle, one more state to describe its appearence when clicked and a last state when the button has the mouse pointer hovering above it.

Programs are another element that we can use to describe how our UI will react to input from the user or the application by referencing to parts and the change of their states (usually as a result of events like mouse clicking or scrolling etc)
Another use of programs is to send out signals to the application that programmers can use to execute specific functions.

Programs must be defined in a brief and clear manner.
For example, to make a button with a full animated effect you must create at least 3 programs
One to handle the transition from the idle/unclicked state to the clicked state.
One more to handle the reverse transition and one more that will fire a signal that the button was pressed, so the application using this button can do something usefull with it.

2. Creating User Interfaces

In this chapter we'll see how we create UIs with edje, always approaching code from a designer's perspective.

2.1 Your first Edje Themes
2.1.1 A taste of properties

If you have any web design experience you will surely know about Cascading Style Sheets (CSS).
In a theoretical manner Edje could be described as a "CSS for Desktop Applications" and thats because of the way one describes elements/graphical properties.
Every Edje element, whether its a group, or a part, or a description (we will see that in a moment) has properties. Some of them are required and some are optional.

Some examples of properties are:

name - The name of the element (usually required)

name: "MyName";

min - The minimum width and height of the element

min: 25 25;

max - The maximum width and height of the element

max: 800 600;

type - The type of the element. Can be TEXT, RECT, TEXTBLOCK, SWALLOW, GROUP, BOX, TABLE or EXTERNAL.

type: RECT;

... and many more properties we can find through the Edje documentation.
As we can see from the examples above to give a value in a property we just need to type its name followed by a colon, then the value or values (depends on the property) we want to assign and finally a semi-colon that shows the end of our statement.

2.1.2 The most simple theme

Bellow there is the "code" for the most simple edje UI possible, explanation given after the code.


    name: "MyOwnGroup";

If you put this code in a file (lets say example1.edc) you can run the command
edje_cc example1.edc in the directory where the file is and a new file named example1.edj
will be created in the same folder. This file is the one that contains all the UI we described in the example1.edc (basically nothing, a blank theme, since its the bare minimum).
You can preview your creation by running the following command:
edje_player example1.edj

So, lets explain the code...
As we saw on chapter 1, a UI needs at least 1 collection and at least 1 group to be valid.
The name property we define in the group was required since its the only group that exists in this edje theme (we would get an error message that our theme does not contain any groups if all groups were anonymous).

2.1.3 Something more complex

In our second example we will make up a UI that has an orange background with a minimum width and height of 150 pixels and maximum width and height of 800 x 600 pixels. Always followed by code explanation.


    name: "Example2";
    min: 150 150;
    max: 800 600;
        name: "MyBackground";
        type: RECT;
          state: "default" 0.0;
          color: 255 128 0 255;

So, lets explain the code... (Coming Soon (tm) )

Imported from
1 drakevr 2012-02-16 04:08:52 first draft / page creation
2 drakevr 2012-02-16 04:36:20 Intro 1.1
3 drakevr 2012-02-16 04:36:49
4 ragecryx 2012-02-16 06:17:45
5 ragecryx 2012-02-16 06:19:06
6 ragecryx 2012-02-16 06:25:32
7 ragecryx 2012-02-16 06:31:34
8 drakevr 2012-02-16 06:42:46 finished 1.1
9 ragecryx 2012-02-16 06:44:08
10 ragecryx 2012-02-16 06:48:37 fixes
11 ragecryx 2012-02-16 06:53:19 content and grammar fixes
12 ragecryx 2012-02-16 06:56:11 microscopic fixes
13 ragecryx 2012-02-16 07:11:30 added image
14 ragecryx 2012-08-20 16:02:27 Added section 1.2
15 ragecryx 2012-08-20 16:43:34 Added section 1.3
16 ragecryx 2012-08-20 17:25:29 Added section 1.4
17 ragecryx 2012-08-20 17:57:29 Initialized chapter 2
18 ragecryx 2012-08-20 18:12:56 Added content in section 2.1.2
19 ragecryx 2012-08-20 18:28:08 Code example 2 in chapter 2
20 ragecryx 2012-08-20 18:43:45 Some fixes in chapter 2
21 drakevr 2012-08-23 03:37:39 miniscule CSS (known name error fix :p)

Last Author
Last Edited
Sep 5 2013, 1:52 PM