[ About ]   [ Contents ]  [ Tutorials ]  [ Advanced ] [ Tips and Tricks ]


Tutorial 1 - The Files

An Enlightenment theme is very complicated, as you probably know already. Your probably wondering what all the .cfg files and images in a theme do, how they work together, etc. At first looks, the BrushedMetal theme looks quite scary. Looking at the theme untarred, you get a BIG list of .cfg and image files, looking in no way like a theme. Well, in this tutorial, I am going to describe what all of the .cfg files in a theme do, how they interact, and how they use all those images to make up a working theme.

As you read in the previous section, an enlightenment theme has several configuration files. Here is the list again:

init.cfg
actionclasses.cfg
imageclasses.cfg
textclasses.cfg
colormodifiers.cfg
windowmatches.cfg
tooltips.cfg
buttons.cfg
borders.cfg
slideouts.cfg
sounds.cfg
menustyles.cfg
cursors.cfg
desktops.cfg
others...

This list is not in any order, and I may have missed a file, but these are the most important files. For an enlightenment theme to work, all of these files MUST, I repeat MUST, be present. If a file is not present, enlightenment will either pop up a ton of error messages on startup, or segfault. Now, even though all of these files must be present does not mean that they need to contain anything. As an example, if you don't want to define any pre-set backgrounds in your theme, you could leave the desktops.cfg file empty. Or if you don't want sounds or slideouts. One thing you may want to do though, as a general rule add the following line to the top every config file, including ones you wish to keep empty:

#include <definitions>

This includes the standard macros and defines required to make an enlightenment theme, and acts as a placeholder for empty config files. More on the definitions file will come later on. You should also add this line to all your config files too, including the empty ones (although it is not necessary for the empty ones):

__E_CFG_VERSION 0

This tells enlightenment what configuration specification you are using. Currently, as far as I know, the only version is 0. Now that you know what files you require, we can move on to what each file does.

The Init.cfg File

The init.cfg file is the starting point of an enlightenment theme. It is parsed first when starting enlightenment, and contains information required for enlightenment to start properly. First, the init.cfg file contains the startup background information. This defines what colors and images you want on the startup screen while enlightenment starts. The file also defines the images and fonts to be used for the progress indicator displayed when enlightenment starts. Lastly, the file contains the images and fonts to be used for the basic enlightenment dialogs, such as the "About Enlightenment" option on the default root menu.

The Actionclasses.cfg File

The actionclasses.cfg file defines everything that happens when you press a button or drag a window or open a menu. This file is probably one of the most confusing, next to the borders.cfg file. An actionclass defines attributes of a button (defined in buttons.cfg), or a border part (defined in borders.cfg). These attributes include what tooltip is displayed when pointed to, what keyboard modifiers are used, and what happens when a button on the mouse is pressed, from executing a program to closing a window. For your theme to be functional and dynamic, actionclasses are required.

The Imageclasses.cfg File

The imageclasses.cfg file defines classes for ALL of the images that are to be used in your theme. An image cannot be directly referenced from a button or a border in an enlightenment theme. Rather, you reference an image class from a button or border, and the image class references the image. This allows for several cool features that let you control how an image is stretched and where text is placed on an image. Image classes are the crux of a theme, and are actually quite basic once you know how to create them. For DR16 themes, the widget and pager images are defined here.

The Buttons.cfg File

The buttons.cfg file defines buttons for your theme. A "button" in enlightenment is much more than just a button. It can be used for many things, from actual buttons that do something to just an image used for looks, such as the macbar in my eMac theme. Buttons can do several things, from running an application to opening a menu or slideout. Button classes must be linked to action classes in order for them to actually do anything.

The Borders.cfg File

The borders.cfg file defines all of the different border types for your theme. Border definitions are probably the most complicated and confusing part of a theme. A border definition controls what images are used for each part of the border, down to the corners. You have the ability to position and align images by the pixel, define what images disappear when the window is shaded, how many buttons and what happens when they are clicked. Every part of a border can be linked to an action class, which in turn defines the parts tooltip and function.

The Textclasses.cfg File

The textclasses.cfg file defines classes for fonts that are to be used in your image. This file is usually fairly small, and very easy to learn. A textclass just defined what type of font to use, the colors, and any effects you may wish to apply (shadow, outline, etc.) These text classes are referred to from the buttons.cfg and borders.cfg files.

The Colormodifiers.cfg File

The colormodifiers.cfg file defines image color modifiers. While still mostly a mystery to me, my basic understanding of the file is this. A colormodifier defines tone curve points, in Red, Green, and Blue, that can be applied to an image. I personally don't have any experience in using color modifiers, so if any one knows how to write and use them, please e-mail me.

The Windowmatches.cfg File

The windowmatches.cfg file defines what border types to use for certain windows. This file is very easy to write, but it can take some time to figure out the names and titles of all the windows you want to assign a special border. Several standard window matches must be defined such as the transient, fixed size, and shaped borders. This file can also be used to assign icons to minimized applications.

The Tooltips.cfg File

The tooltips.cfg file defines the images to be used in your tooltips. Enlightenment allows for up to 5 images to be used in your tooltip. You also define what text class to use on the tooltip.

The Slideouts.cfg File

The slideouts.cfg file defines the slideouts to be used in your theme. A slideout consists of several images that slide in one of 4 directions when the slideout is called. Once a button on the slideout is clicked, the buttons dissapear until the slideout is called again. Probably the most basic configuration file of an enlightenment theme.

The Sounds.cfg File

The sounds.cfg file defines all the sounds to be used in your theme and what event they occur at. Enlightenment currently only supports a few sounds, and sounds usually add a lot to the size of your theme, but can add that last little touch that makes a theme complete.

The Menustyles.cfg File

The menustyles.cfg file defines menu border style names. The menus styles file is necessary in a theme, and several menu styles MUST be defined for a theme to work. The standard menus.cfg file, located in your enlightenment root directory under /config, references these standard menu styles, and if one is not found in a theme, enlightenment can segfault. This file is relatively simple to write.

The Cursors.cfg File

The cursors.cfg file defines what cursors are available in your theme. Each cursor in your theme must have a cursor image and cursor mask file. The cursors.cfg file assigns names to these images and masks, and also lets you modify the color of the cursor. Enlightenment currently only supports basic, 2 color cursors. The cursor images and masks are simple xbm images, slightly modified.

The Desktops.cfg File

The desktops.cfg file defines your themes backgrounds. Not necessary, and sometimes overridden by the user, the desktops.cfg file allows you to define colors and images to be used on each of enlightenment's 32 desktops. These backgrounds do not change each "virtual screen", but each "page" of enlightenment's desktops.

 


[ Prev ] [ Next ]