I’m often introducing new developers to Evas, part of the Enlightenment Foundation Libraries (EFL), and one common problem is to understand how Evas, Smart Objects and Edje integrates. Yesterday, while teaching some guys here at ProFUSION I came to the following picture, that describes it well:
Evas exposes just a handful object types, like solid color rectangle, gradient rectangles, images, text, text block, polygon, line and smart object.
Smart Object is the only special type because it’s extensible and developers should implement its virtual methods to have it to behave like regular objects with calls like evas_object_color_set() or evas_object_resize(). Smart Objects do not have any visual representation, they can contain other objects that may have it, like images or rectangles, that’s why they’re represented like a box in the figure above. Their children are handled as if they were in a special layer: outside objects cannot interleave smart object children. It’s recommended as good practice to not expose children to outside, instead provide methods to manipulate these children.
A regular mistake is to forget that just creating objects from inside smart object methods don’t make them children! You must assign a parent to a child with evas_object_smart_member_add(child, parent). You can “unparent” them with evas_object_smart_member_del(child). As children can not have more than one parent, adding a new parent to the child will first remove its parent before adding the new one.
Edje is a smart object that loads a group of parts from a description file often called “EDJ” (or edje file). These files contains a collection of groups, each with a set of parts (evas objects), each part with various states. When a group is assigned to some Edje object with edje_object_file_set(object, file_name, group_name) the parts are created in order (first will go first, thus will stay at the bottom) using the "default" 0.0 state. If some part have relative positioning to the whole available space (Edje object geometry), when the edje object is changed, all the dependent parts are recalculated and have their geometry set. If some part is relative to other parts, then when one of these changes, the dependent part is recalculated and reset as well. One can manipulate edje by changing the state of the parts, this should be done by means of programs, which will act based on signals. Edje will dispatch some signals like "resize", "mouse,move" and "show", but users are encouraged to create their own application signals that can be emitted with edje_object_signal_emit(object, "signal", "source").
The most common mistake using Edje is to touch its children. Never, ever, change the object that you get with edje_object_part_object_get(). That call is for inspection purposes only. You’re just allowed to change Edje by emitting signals from your application, EDJ should have programs to catch that signal and trigger some state change on some parts. Let’s remember that it’s recommended to never changed smart object children, Edje is strict, making this a rule. What can you expect if you break this rule? Before, I said that Edje would recalculate dependent parts when the dependency changes, but I lied: for simplicity purposes, when something change, Edje recalculates the whole thing, and it does so using the state information from EDJ, not the current value of the object. If you change the color of some rectangle from white to black, recalculation will enforce the rectangle to be white. Same for images, if you set the image file to be something else, it will be restored to the image specified in the EDJ.
One variation of this mistake is dealing with SWALLOW parts. These parts enable user to add an external object to be managed by Edje with the edje_object_part_swallow(object, "part_name", external_object). As said, Edje will manage this external object: it will become the object’s parent, it will set clippers, colors, visibility and geometry. After that call, user don’t own the object anymore, he is only allowed to change other, non managed properties, ie: images can have their file set because SWALLOW parts don’t have any image property (unlike IMAGE parts!)
It’s very important to understand these concepts. Real applications are a mix of smart objects and edje, one inside the other, which might led to great confusion if management ownership is not clear.
In the figure above we can see the management ownership to avoid these problems. User manages both the smart object and the background. In order to change the edje he should call some API defined in the smart object. To change the “star” image, user should call smart object that would call edje.
You can also download the printable version of the figure.
