JackLab/Basic Theming Tutorial

From openSUSE

Basic Theming Tutorial:

E17 has a very powerful theming engine which is far ahead of its competition, but this also means that creating themes is more difficult than for most (at least minimalistic) window managers. Almost everything that the user sees in E17 is defined by the theme, and can look completely different, to the point where one cannot even notice that it is the same program. Theming isn't that difficult though, it just takes a while to get used to the new system. This tutorial is meant to function as a light introduction to E17 theming. There will be a more technical in-depth theming tutorial on Get-E.org later once it's complete. This one should be enough to be able to get started with E17 theming though. If you feel that there's anything theming related that belongs to user-level documentation, but is missing here, please contact us so we can try to add it.

As already mentioned, you need to know that the E17 theme format is not final yet. Every now and then new elements and features are added to the default theme format. If a theme isn't properly maintained to keep up with the development in CVS, it will eventually become unusable.

All E17 themes, as mentioned earlier in this guide, need to be in a binary EDJ format. All correctly built binary Edje files can be decompiled with the following command:

edje_decc /path/to/theme.edj

Not all themes decompile correctly though, as the theme may be missing certain decompile information. Most themes should decompile fine though. Unfortunately, the default theme is an exception - it does currently not decompile cleanly. However, the source files for the default theme are included with the source for E17 itself. E17 themes contain both Edje code (.edc files) and various images that are used for the graphical user interface itself.

There's not much official documentation available for Edje at this point, so if you wish to learn it (for example for customizing themes/creating your own backgrounds), the best way to learn is to decompile various Edje files and look at the code itself. For the programmers out there, Edje code is C style, it can be understood by the C preprocessor, but the constructs and keywords etc are Edje. An EDJ file normally consists of one or more actual Edje code files (files that end with .edc) and then there are the images the theme itself uses.

This tutorial will use the default theme as the example, but the same system should apply to most other themes as well. Let's start by building a local directory that contains all the necessary files to build the default E17 theme. In most cases this same directory can be created by simple decompiling the theme as mentioned above. In this case that won't be possible though, since we are using the default E17 as the example, so you'll need to go to go to your E17 source directory and enter data/themes. From this directory you can see most of the files the default theme contains. Before you start, you'll need to know that if you compile the theme this way, the seconds will not display in the clock because of a certaiin E17 profile problem that we haven't managed to find the solution to yet. But there should be one soon, we'll update this guide as soon as we get to know how to fix it. If this doesn't bother you, copy all .edc files from this directory to a local directory of your choice:

cp /path/to/E17-source-dir/data/themes/*.edc /home/username/e17-theme-default

Next you will need to copy all images from the data/themes/images directory to your local E17 default theme source directory:

cp /path/to/E17-source-dir/data/themes/images/*.png /home/username/e17-theme-default

Now we have a local directory with all the required graphics and Edje code files, but a few things are still missing. First, you need to create a bash script called build.sh in the directory. The script needs to contain the following:

1. !/bin/sh

edje_cc $@ --image_dir . --font_dir . default.edc -o custom.edj

This is a simple bash script that runs the edje_cc program (a tool for creating binary EDJ files), and tells it that all the files required for the theme are in the present directory. Running this script inside the directory will, once the directory has all the necessary files, compile the theme into binary EDJ form. The created file's name in this case will be custom.edj. Last but not least, you need to copy two font files to the same directory. These fonts are already on your system if you've installed E17.

cp /usr/share/enlightenment/data/fonts/Vera.ttf /home/username/e17-theme-default cp /usr/share/enlightenment/data/fonts/VeraBd.ttf /home/username/e17-theme-default

Now you should be able to compile a version of the default theme by running the build.sh script. As already mentioned, the filename of the created file is custom.edj, but you can of course just edit the build.sh script if you want to change that. You may want to create a few copies of this directory if you start creating a custom theme. Now that the build directory is complete and has everything that's needed, let's take a look at the individual files themselves. The main Edje code file, that in this case specifies what fonts and other Edje code files are used/loaded, is default.edc. It looks like this:

#ifdef E17_PROFILE
# if E17_PROFILE == LOWRES_PDA
#  define SM "sm_"
# elif E17_PROFILE == MEDIUMRES_PDA
#  define SM "sm_"
# elif E17_PROFILE == HIRES_PDA
#  define SM "sm_"
# elif E17_PROFILE == SLOW_PC
#  define SM "sm_"
# elif E17_PROFILE == MEDIUM_PC
#  define SM
# elif E17_PROFILE == FAST_PC
#  define SM
# endif
#else
# define SM
#endif

fonts {
   font: "Vera.ttf"   "Edje Vera";
   font: "VeraBd.ttf" "Edje Vera Bold";
}

collections {
#include "default_background.edc"
#include "default_battery.edc"
#include "default_border.edc"
#include "default_clock.edc"
#include "default_gadman.edc"
#include "default_ibar.edc"
#include "default_menu.edc"
#include "default_pager.edc"
#include "default_resize.edc"
#include "default_move.edc"
#include "default_temperature.edc"
#include "default_error.edc"
#include "default_cpufreq.edc"
#include "default_ibox.edc"
#include "default_start.edc"
#include "default_winlist.edc"
#include "default_transitions.edc"
#include "default_dialog.edc"
#include "default_desktopname.edc"
#include "default_icons.edc"
} 

As you can see, this file is simply a list of which font and Edje code files are being used in the theme. The individual .edc files listed specify how that part of E17 functions, which images are loaded for that part, and of course how the images are used in constructing the graphical user interface. As you can see, most modules for example have their own Edje code file. Most of these theme .edc files start by defining the images used. Needless to say, a theme contains a large number of PNG images. If all you want to do is change some artwork, perhaps icons or a default background for a certain module, that can usually be done by simply overwriting the corresponding image with your custom one. If you wish to change something more in-depth, for example create something completely original, you'll need to learn to code Edje. The best way to learn is to look at how different themes' Edje code files.

For example default_icons.edc starts like this:

images {
  image: "e17_icon_e_0.png" LOSSY 90;
  image: "e17_icon_e_glow_0.png" LOSSY 90;

  image: "e17_icon_power_button_0.png" LOSSY 90;
  image: "e17_icon_power_button_glow_0.png" LOSSY 90;

  image: "e17_icon_reset_button_0.png" LOSSY 90;
  image: "e17_icon_reset_button_glow_0.png" LOSSY 90;

  image: "e17_icon_theme_0.png" LOSSY 90;
  image: "e17_icon_theme_glow_0.png" LOSSY 90;

  image: "e17_icon_windows.png" LOSSY 90;

  image: "e17_icon_module.png" LOSSY 90;

  image: "e17_icon_favorites.png" LOSSY 90;

  image: "e17_icon_desktop.png" LOSSY 90;

  image: "e17_icon_gadget.png" LOSSY 90;

  image: "e17_icon_configuration.png" LOSSY 90;
  image: "e17_icon_run.png" LOSSY 90;

}

After this there's alot of functionality related Edje code, but for simple changes, for example if you wish to change the default menu icons, you could simply replace these files listed here with your own custom graphics and then recompile the theme.

Another example would be changing or adding fonts to the default theme. If you take a look at default.edc, you simply have to add your font TTF files here and move them to the theme build directory:

fonts {
  font: "Vera.ttf"   "Edje Vera";
  font: "VeraBd.ttf" "Edje Vera Bold";
  font: "NewFont.ttf" "New Font";
  font: "NewFontBd.ttf" "New Font Bold";

}

Now you can search the various Edje code files (.edc) for the string "font:" and simply edit that section to use the new font in the theme. For example if you want your new font to be used in the window border title bar, the section you need to edit in default_border.edc is:

           text {
              text:     "";
              font:     "Edje Vera";
              size:     10;
              min:      0 1;
              align:    0.0 0.5;
              text_class: "title_bar";
           }

And to change the same font to be used in the E17 menu, you would need to edit default_menu.edc in this section:

            text {
              text:     "Item Label";
              font:     "Edje Vera";
              size:     10;
              min:      1 1;
              align:    0.0 0.5;
              text_class: "menu_item";
           }

In both cases, you can simply replace the "Edje Vera" text with "New Font", depending on how you named it. To edit colors, you need to look for lines in the Edje code files (.edc) that start with "color:", for example:

color:    255 255 255 0;

These four values are an RGBA code. The first three are the standard RGB code, and the last number is the level of transparency (255 is no transparency, while 0 is invisible). The four numbers in the example mean a fully white text with full maximum transparency, in other words this color is invisible.

We know this guide isn't very comprehensive, but with some luck it might be enough to be able to get started with E17 theming. If you take a look at other E17 themes, most of them share the same structure and thus it's pretty easy to for example combine parts of themes, as the theme structure is modular (there are several .edc files, and each defines a small part of the graphical user interface).