Edje

What is Edje?

Edje is a complex graphical design & layout library based on Evas that provides an abstraction layer between the application code and the interface, while allowing extremely flexible dynamic layouts and animations.

In more popular terms, Edje makes every application that uses it "skinable" .

"Edje is an attempt to find a middleground between theming and programming without turning the theme itself into just yet another program."
-- Carsten Haitzler (The Rasterman)

It's purpose is to be a sequel to "Ebits" which to date has serviced the needs of Enlightenment development for version 0.17. The original design parameters under which Ebits came about were a lot more restricted than the resulting use of them, thus Edje was born.

Edje is a more complex layout engine compared to Ebits. It doesn't pretend to do containing and regular layout like a widget set. It still inherits the more simplistic layout ideas behind Ebits, but it now does them a lot more cleanly, allowing for easy expansion, and the ability to cover much more ground than Ebits ever could. For the purposes of Enlightenment 0.17, Edje should serve all the purposes of creating visual elements (borders of windows, scrollbars, etc.) and allow the designer the ability to animate, layout and control the look and feel of any program using Edje as its basic GUI constructor. This library allows for multiple collections of Layouts in one file, sharing the same image database and thus allowing a whole theme to be conveniently packaged into 1 file and shipped around.

Edje, unlike Ebits, separates the layout and behavior logic. Edje files ship with an image database, used by all the parts in all the collections to source graphical data. It has a directory of logical part names pointing to the part collection entry ID in the file (thus allowing for multiple logical names to point to the same part collection, allowing for the sharing of data between display elements). Each part collection consists of a list of visual parts, as well as a list of programs. A program is a conditionally run program that if a particular event occurs (a button is pressed, a mouse enters or leaves a part) will trigger an action that may affect other parts. In this way a part collection can be "programmed" via its file as to hilight buttons when the mouse passes over them or show hidden parts when a button is clicked somewhere etc. The actions performed in changing from one state to another are also allowed to transition over a period of time, allowing animation.

This separation and simplistic event driven style of programming can produce almost any look and feel one could want for basic visual elements. Anything more complex is likely the domain of an application or widget set that may use Edje as a convenient way of being able to configure parts of the display.

How does Edje work?

Edje internally holds a geometry state machine and state graph of what is visible, where it is, its size, colors, etc. This information is stored on a .eet file. These files are produced by the edje_cc tool, which takes a text file (.edc) as input and "compiles" it onto the .eet (information, images, fonts and any other data needed).

What does Edje require?

Edje requires fairly little of your system. To use the Edje runtime library you need:

• Evas (library): Edje needs Evas to be built with at least PNG and EET image loaders. Edje uses X for the test program, so you will need the SOFTWARE_X11 engine built into Evas as well. A suggested configure list is below in the "cheat sheet" for Evas
• Ecore (library): Edje also needs Ecore to be built with at least ECORE_EVAS and ECORE_X modules. Even though, it's suggested a full build of the Ecore library
• Eet (library)

Scripting inside Edje

Edje supports two scripting languages: Embryo and Lua.

Embryo

Please refer to Embryo for more information.

Lua

Lua scripts are declared with the lua_script keyword. Inside a lua_script code block, there's a reference to your edje named ed, which you may use for accessing your parts, as shown on the second example (e.g. a part named "label" is accessed through ed.label).

Classes and Attributes

General Objects

Within the lua_script scope, Edje objects (groups, parts, etc) have the following basic attributes and methods:

objects methods

• EdjeObject.del()
• EdjeObject.show()
• EdjeObject.hide()
• EdjeObject.move(x, y)
• EdjeObject.resize(w, h)
• EdjeObject.raise()
• EdjeObject.lower()
• EdjeObject.stack_above()
• EdjeObject.stack_below()
• EdjeObject.clip_unset()

objects attributes

• EdjeObject.name
• EdjeObject.geometry: (x, y, width, height)
• EdjeObject.type: object type (RECT=1, TEXT, IMAGE, SWALLOW, TEXTBLOCK, GRADIENT, GROUP, BOX, TABLE, EXTERNAL)
• EdjeObject.layer
• EdjeObject.above
• EdjeObject.below
• EdjeObject.size_hint_min
• EdjeObject.size_hint_max
• EdjeObject.size_hint_request
• EdjeObject.size_hint_aspect
• EdjeObject.size_hint_align
• EdjeObject.size_hint_weight
• EdjeObject.size_hint_padding
• EdjeObject.visible
• EdjeObject.render_op
• EdjeObject.anti_alias
• EdjeObject.scale
• EdjeObject.color: (r, g, b, alpha)
• EdjeObject.color_interpolation
• EdjeObject.clip
• EdjeObject.clipees
• EdjeObject.evas
• EdjeObject.pass_events
• EdjeObject.repeat_events
• EdjeObject.propagate_events
• EdjeObject.focus
• EdjeObject.pointer_mode
• EdjeObject.precise_is_inside
• EdjeObject.mouse_events
• EdjeObject.mouse: (x,y) position

Groups

Groups are objects, that is, they inherit the methods listed above. They also contain the following methods and attributes:

groups methods

• EdjeGroup.timer(secs, callback)
• EdjeGroup.animator(func)
• EdjeGroup.poller(interval, callback)
• EdjeGroup.transform()
• EdjeGroup.signal_emit(emission, source)
• EdjeGroup.message_send(message_type, id, msg)
• EdjeGroup.program_run(name)
• EdjeGroup.program_stop(name)
• EdjeGroup.signal_callback_add(emission, source, callback)
• EdjeGroup.signal_callback_del(emission, source)
• EdjeGroup.freeze()
• EdjeGroup.thaw()

groups attributes

• EdjeGroup.group
• EdjeGroup.mouse
• EdjeGroup.mouse_buttons
• EdjeGroup.size_min
• EdjeGroup.size_max
• EdjeGroup.scale
• EdjeGroup.load_error
• EdjeGroup.load_error_str
• EdjeGroup.play
• EdjeGroup.animation
• EdjeGroup.frametime

Parts

Parts are objects, that is, they inherit the methods listed above for general objects. They also contain the following methods and attributes:

parts methods

• EdjePartDescription EdjePart.custom_state(state_name, state_val)
• void EdjePart.swallow(obj)
• void EdjePart.unswallow()
• void EdjePart.text_select_none()
• void EdjePart.text_select_all()
• void EdjePart.text_insert(text)
• bool EdjePart.table_pack(child, row, colspan, rowspan)
• bool EdjePart.table_unpack(child)
• bool EdjePart.table_clear(clear)
• bool EdjePart.box_append(item)
• bool EdjePart.box_prepend(item)
• bool EdjePart.box_insert_before(item, before)
• bool EdjePart.box_insert_at(item, index)
• EdjePart EdjePart.box_remove(item)
• EdjePart EdjePart.box_remove_at(item, index)
• bool EdjePart.box_remove_all(clear)

parts attributes

• EdjePart.Swallow
• EdjePart.type
• EdjePart.effect
• EdjePart.mouse_events
• EdjePart.repeat_events
• EdjePart.states_list
• EdjePart.state
• EdjePart.text
• EdjePart.text_selection
• EdjePart.text_cursor_geometry:
• EdjePart.geometry
• EdjePart.part_col_row_size
• EdjePart.drag_dir
• EdjePart.drag_value
• EdjePart.drag_size
• EdjePart.drag_step
• EdjePart.drag_page
• EdjePart.tween_state

Parts States Descriptions

Among edje, states are defined by description{} blocks, specified by a name and a number (e.g. "default" 0.0), as shown below:

collections {
    group {
        parts {
            part {
                name: "mypart";
                description {
                    state: "default" 0.0;
                    // ...
                }
                description {
                    state: "some_other_state" 0.0;
                    // ...
                }
            }
        }
    }
}

For accessing a part's description through Lua, one must use the ed.<part_name>:custom_state() method. For example, for retrieving the description "some_other_state" 0.0, one must do:

   lua_script {
      desc_obj = ed.mypart:custom_state("some_other_state", 0.0)
   }

This description object contains the following attributes (no methods):

description attributes

• EdjePartDescription.alignment
• EdjePartDescription.min
• EdjePartDescription.max
• EdjePartDescription.step
• EdjePartDescription.aspect
• EdjePartDescription.aspect_pref
• EdjePartDescription.color
• EdjePartDescription.color2
• EdjePartDescription.color3
• EdjePartDescription.color_class
• EdjePartDescription.rel1
• EdjePartDescription.rel1_to
• EdjePartDescription.rel1_offset
• EdjePartDescription.rel2
• EdjePartDescription.rel2_to
• EdjePartDescription.rel2_offset
• EdjePartDescription.image
• EdjePartDescription.border
• EdjePartDescription.fill_smooth
• EdjePartDescription.fill_pos
• EdjePartDescription.fill_size
• EdjePartDescription.text
• EdjePartDescription.text_class
• EdjePartDescription.text_font
• EdjePartDescription.text_style
• EdjePartDescription.text_size
• EdjePartDescription.text_fit
• EdjePartDescription.text_min
• EdjePartDescription.text_max
• EdjePartDescription.text_align
• EdjePartDescription.visible

Images Parts

images parts attributes

• EdjeImagePart.file
• EdjeImagePart.fill
• EdjeImagePart.fill_transform
• EdjeImagePart.alpha

Line parts

line attributes

• EdjeLinePart.xy

Polygon parts

polygon methods

• EdjePolygonPart.point_add()
• EdjePolygonPart.points_clear()

Table parts

table methods

• EdjeTablePart.pack()
• EdjeTablePart.unpack()
• EdjeTablePart.clear()

table attributes

• EdjeTablePart.homogeneous
• EdjeTablePart.padding
• EdjeTablePart.align
• EdjeTablePart.col_row_size
• EdjeTablePart.children

Examples

Example 1: hello world

collections {
    group {
        name: "main";
        parts {
            lua_script {
                print("Hello world!")
            }
        }
    }
}

Example 2: hello world button

collections {
    group {
        name: "main";
        parts {
            part {
                name: "bg";
                type: RECT;
                description {
                    state: "default" 0.0;
                    color: 255 255 255 255;
                    rel1.relative: 0.0 0.0;
                    rel2.relative: 1.0 1.0;
                }
            }

            part {
                name: "button_box";
                type: RECT;
                description {
                    state: "default" 0.0;
                    color: 200 200 200 255;
                    rel1 {
                        to: "bg";
                        relative: 0.4 0.4;
                    }
                    rel2 {
                        to: "bg";
                        relative: 0.6 0.6;
                    }

                    program {
                        signal: "mouse,down,1";
                        source: "button_box";
                        action: STATE_SET "pressed" 0.0;
                        target: "button_box";
                        lua_script {
                            print("Hello World!")
                            ed.label.text = "Hello world!"
                        }
                    }
                }

                description {
                    state: "pressed" 0.0;
                    inherit: "default" 0.0;
                    color: 30 30 30 25;

                    program {
                        signal: "mouse,up,1";
                        source: "button_box";
                        action: STATE_SET "default" 0.0;
                        target: "button_box";
                        lua_script {
                            print("Mouse up")
                            ed.label.text = "Say hello."
                        }
                    }
                }
            }

            part {
                name: "label";
                type: TEXT;
                mouse_events: 0;
                effect: SOFT_SHADOW;
                description {
                    state: "default" 0.0;
                    color: 0 0 0 255;
                    text {
                        text: "Say hello!";
                        font: "Sans";
                        size: 14;
                        align: 0.5 0.5;
                    }
                    rel1 {
                        to: "button_box";
                        relative: 0.0 0.5;
                    }
                    rel2 {
                        to: "button_box";
                        relative: 1.0 1.0;
                    }
                }
            }
        }
    }
}