Debugging Edje Themes (EDC) with Edje Player

http://brunodilly.org/blog/debugging-edje-themes-edc-edje-player/

After a few years writing Edje themes and leading teams doing such task, I’ve faced some errors and I’m going to list them and explain how to start to debug it with a specific tool:edje_player.

General explanations

Edje is the graphical design library, part of the Enlightenment Foundation Libraries. Themes are written as plain texts following theEdje Data Collections syntax and compiled with the program edje_cc. Later, it can be used by any program usingEdje API.

Communication between code and theme is done via signals and messages. Signals are composed by two strings,source andsignal and can be listened or emitted by aprogram block in the theme without the need of scripts. Messages can be more complex, can be a float, an integer, a string, an array of these types or a composition, like a string + a float, for example. Also, messages have identifier number. But to handle messages, the theme needs scripts.

So it is a bit error prone regarding typos, since it wouldn’t be checked in compile time (this issue can be reduced with the recently added codegen). Also, many other issues can happen, like a part not appearing where you expected, or a transition that doesn’t seem to be triggered.

Edje Player, more than just a tool used to visualize the theme, can be used to debug it. Between many options, the more relevant are:

• -g –group : an edc file can have many groups, so if you want to load a group different from “main”, or from the first group of the collection, it should be used. E.g.: edje_player -g groupname file.edc. If you can’t remember the group name, groups can be listed with “–list-groups” option.
• -Z –size : will try to set a specific size, but minimum sizes will be respected. If not set it will try a default size (that also will respect theme minimum size). E.g.: edje_player -Z 500×500 file.edc
• -p –print : used to print signals and messages emitted by the theme to stdout. E.g.: edje_player -p file.edc
• -S –slave-mode : really useful mode that will make edje player listen for commands on stdin. E.g.: edje_player -S file.edc. Main commands:
  • help: list all possible commands
  • signal <emission> <source> : send a signal to edje. If whitespaces are required the string should use double quotes. E.g.: signal “play next” player
  • message <id> <type> <args list>: sends a message to edje. It supports all message types, and args list can vary depending on them, so check the list withhelp. E.g.: message 2 Float 0.4

Troubleshooting

Usually when facing the following issues, an inexperienced developer tends to waste a lot of time digging into themes code just to get to the conclusion that it was an error in the program code, or make many changes to the program code to trigger the issue more easily or to print debugging information, like adding callbacks to signal “*” “*” of some objects.

So, as a first step, it’s required to check if it’s an issue on the theme or the program code, and I’m providing some suggestions of how to validate the theme using edje_player in many cases.

A general advice: check for typos in signals / sources and part names (for the case of swallows). To prevent it if used in more than one place, you could define a constant.

Animation to be tested is hard to trigger

Suppose you need to test / debug an animation that is triggered only after many interactions in your software, or it only happens after a long task. If the theme program that starts it listens for a signal or message, you can send it using Edje Player slave mode and save a lot of time. If the program is called by others using the after command or via script, you can add a signal there just for debugging purposes (or call the parent program of the whole chain).

Part with apparently wrong geometry

Using the info command of slave mode it will return the geometry of the part.
E.g.: info bg => INFO: “bg” 0,0,512,380

These four values are x and y coords, width and height of the part named “bg”.

If you receives the expected size, but yet theme looks wrong, and if the part is a swallow or text, many issues can be happening, like the swallowed object having a problem instead of the theme. In this case, you can change its type for a rectangle just to validate the part sizing.

Transition triggered by signal doesn’t play

If a transition that should be triggered by a signal doesn’t play, first thing to check is if it is an issue with the transition itself or it is the signal not being emitted by the code. For that, just use thesignal command of the slave mode. If the transition plays, you know the theme is fine, you should look for a typo on signal emission on program code or check if it’s not being emitted at all.

Transition triggered by message doesn’t play

The same approach as transition triggered by signal should be used, but here, instead of typos on signal / source, you need to assure the message id and type are correct (or any other checks you are doing in your script). Using themessage command of the slave mode is enough for an initial investigation.

Callback of signal or message isn’t called

To check if a theme is emitting a signal or message, you can run edje_player with -p argument. In this case, all the emitted signals and messages will be printed to stdout. If the emission you are looking for is done after a user interaction like clicking a part, dragging, mouse over, etc., just do it and you should read it in your terminal.

If the theme should emit it after a signal or message emitted by the program code, you should run edje player with -p and-S arguments, so it will also run in slave mode. For signals, usesignalcommand, for messages, message command.

If you can see the signal / message emitted by the theme in your terminal, the theme is validated. You should check for:

• typos of signal / message
• callback added to the wrong object
• code that adds the callback isn’t even called.
• callbacks are deleted before signal / message emission.

Script variables debugging

Embryo scripts run in a sandbox, you can’t print to terminal directly to see a variable value. An easy way to check these values is to send signals or messages with the variables to be checked and run edje player with -p argument, so they will be print to stdout. With that you can inspect integer, string or float variables.

Signals are sent in embryo with emit(signal, source) and messages are sent in embryo withsend_message(type, id, values list). For a full list of supported functions by embryo script, check the following files:

• INSTALL_PREFIX/share/edje/include/edje.inc
• INSTALL_PREFIX/share/embryo/include/default.inc

Example

A simple example of a theme that shows a background with a message to the user explaining it will emit a signal back when it receives ‘hello’ from source ‘player’:

/* Simple EDC exemplifying how to receive and emit signals */

collections {
   group {
      name: "main";

      parts {
         part {
            name: "bg";
            type: RECT;
            mouse_events: 0;
            description {
               state: "default" 0.0;
               min: 500 50;
               max: 500 50;
               color: 0 0 0 255;
            }
         }

         part {
            name: "text";
            type: TEXT;
            mouse_events: 1;
            description {
               state: "default" 0.0;
               color: 255 255 255 255;
               text {
                  font: "Sans";
                  size: 20;
                  text: "I will reply to the signal 'hello' 'player'";
               }
            }
         }
      }

      programs {
         program {
            name: "reply";
            signal: "hello";
            source: "player";
            action: SIGNAL_EMIT "hi" "theme";
         }
      }
   }
}

It should be compiled and played:

edje_cc signals.edc
edje_player -p -S signals.edj

It will start sending some signals by default to the theme. After that, you can move the mouse cursor over the text. It will emit signals related to mouse movement. It will print in output:

SIGNAL: "mouse,in" "text"
SIGNAL: "mouse,move" "text"
SIGNAL: "mouse,move" "text"
SIGNAL: "mouse,out" "text"

This kind of signals are not emitted when the cursor moves over the background because the “bg” part was set to not handle it with “mouse_events: 0”.

To emit the ‘hello’ signal, just type:

signal hello player

and you’ll see the following output:

SIGNAL: "hello" "player"
SIGNAL: "hi" "theme"