# The theme format

The theme desctiptions are stored in XML format, so it's an advantage if you know the basics of XML (or just look at the theme files that come with &EasySok;). The DTD of the theme files can be found (after you have installed &EasySok;) in `$(KDEDIR)/share/apps/easysok/theme` and is called `easysoktheme.dtd`.

The theme file itself is just a descriptions of the images used for the different fields. If the field contains a keeper you also have the option to create four different sets of images depending on the direction the keeper is looking or just one set of images for all four directions (e.g. you can use KeeperOnFloor if the keeper looks the same in all directions or LeftKeeperOnFloor etc. if the look depends on it's looking direction).

The root element EasySokTheme has an attribute name, which sets the name of the theme. If the attribute image is given, it is considered the name of the background image to use. The background image itself is searched in the wallpaper directory of KDE (so don't use an absolute filename). You can also set a background color (which will be used if the image is not found or not given). Just specify it with the red, green and blue attributes (the alpha attribute is currently simply ignored here). The values should be in the range [0:255]. You can also add an additional border around the theme. Just use the leftborder, rightborder, upborder and downborder attributes which accept floating point values. A value of 0 means no border, 1 is a border of one field, 0.5 a border of a half field and so on. You can also use negative values.

In the root element you specify the images for all elements. You can specify zero or more PieceImageAlternates for every element (except for the Wall and Outside elements, which expect zero or more WallPieceAlternates). Which of the alternates is used for a specific field is determined by the neighbourhood of the field. If you don't specify any attributes in an alternate, it matches all neighbourhoods. This means if you have for example three alternates with no attributes the field will consist of the overlaid images of the alternates. Just look at the DTD to see the attributes and their legal values.

An alternate itself consists of one or more PieceImage. The piece images itself describe the image used. If there is more than one piece image, the index of the image used is calculated by

    x + y % nr_of_piece_images

x is the x-coordinate of the field and y the y-coordinate (the upper left field is (0,0), the one right to this field is (1,0) and so on). nr_of_piece_images is the number of piece images in the alternate.

A piece image itself consists of zero of more layers and an optional global effect. The layers itself are combined to one image, where the last layer lays on top. The global effect is applied after the layers are combined. Each piece image must have a size (given in the size attribute). This is the width and height of the created image (the combined layers are automatically cropped to this size). You can also add an xoffset and yoffset (look at the KSokoban theme for an example).

A Layer can either consist of an image (given in by the image attribute), which is searched in `$(KDEDIR)/share/apps/easysok` or a color (specified by the red, green, blue and alpha attributes). If you specify only a color, this will result in an image of the size given in the enclosing piece image. You can also give an effect in the layer element, which will be applied to the create image.

The effect element just holds zero or more effects. Currently &EasySok; supports the following effects:

- RotateLeft rotates the image left.

- RotateRight rotates the image right.

- UTurn rotates the image 180 deg.

- Move moves the image by the number of pixels given in xoffset and yoffset. Pixels which fall outside are deleted.

- BlendRgb blends the image to the given color. The factor attribute determines the ammount of blending and should be in the range [0:1]. Note that only the rgb channels are blended

- BlendRgba blends the image to the given color. The factor attribute determines the ammount of blending and should be in the range [0:1]. Note that the rgb channels and the alpha channel are blended.

- BlendAlpha blends the image to the given alpha value. The factor attribute determines the ammount of blending and should be in the range [0:1].

- Colorizes colorizes the given image. The difference to blend is, that the brightness is preserved. The factor attribute determines the ammount of colorizing. Just try this effect, to see the result.

- Scale scales the image to the size given by the width and height attributes.

- Crop crops the image. You give a xoffset and yoffset and the new width and heigh.