<sect1 id="theme-format">
<title id="theme-format.title">The theme format</title>
<para>
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 <filename class="directory">$(KDEDIR)/share/apps/easysok/theme</filename>
and is called <filename>easysoktheme.dtd</filename>.
</para><para>
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 <quote>KeeperOnFloor</quote> if the keeper looks the
same in all directions or <quote>LeftKeeperOnFloor</quote> etc. if the
look depends on it's looking direction).
</para><para>
The root element <quote>EasySokTheme</quote> has an attribute <quote>name</quote>,
which sets the name of the theme. If the attribute <quote>image</quote> 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 <quote>red</quote>,
<quote>green</quote> and <quote>blue</quote> attributes (the <quote>alpha</quote>
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 <quote>leftborder</quote>, <quote>rightborder</quote>,
<quote>upborder</quote> and <quote>downborder</quote> 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.
</para><para>
In the root element you specify the images for all elements.
You can specify zero or more <quote>PieceImageAlternates</quote> for every
element (except for the <quote>Wall</quote> and <quote>Outside</quote> elements,
which expect zero or more <quote>WallPieceAlternates</quote>).
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.
</para><para>
An alternate itself consists of one or more <quote>PieceImage</quote>.
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
</para><screen>x + y % nr_of_piece_images</screen><para>
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.
</para><para>
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 <quote>size</quote>
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 <quote>xoffset</quote> and <quote>yoffset</quote>
(look at the KSokoban theme for an example).
</para><para>
A <quote>Layer</quote> can either consist of an image (given in by
the <quote>image</quote> attribute), which is searched in
<filename class="directory">$(KDEDIR)/share/apps/easysok</filename> or
a color (specified by the <quote>red</quote>, <quote>green</quote>, 
<quote>blue</quote> and <quote>alpha</quote> 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.
</para><para>
The effect element just holds zero or more effects.
Currently &EasySok; supports the following effects:
</para>
<itemizedlist mark="opencircle">
<listitem><para>
<quote>RotateLeft</quote> rotates the image left.
</para></listitem><listitem><para>
<quote>RotateRight</quote> rotates the image right.
</para></listitem><listitem><para>
<quote>UTurn</quote> rotates the image 180 deg.
</para></listitem><listitem><para>
<quote>Move</quote> moves the image by the number of pixels given
in <quote>xoffset</quote> and <quote>yoffset</quote>. Pixels which fall
outside are deleted.
</para></listitem><listitem><para>
<quote>BlendRgb</quote> blends the image to the given color.
The <quote>factor</quote> attribute determines the ammount of blending
and should be in the range [0:1]. Note that only the rgb channels
are blended
</para></listitem><listitem><para>
<quote>BlendRgba</quote> blends the image to the given color.
The <quote>factor</quote> 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.
</para></listitem><listitem><para>
<quote>BlendAlpha</quote> blends the image to the given alpha value.
The <quote>factor</quote> attribute determines the ammount of blending
and should be in the range [0:1].
</para></listitem><listitem><para>
<quote>Colorizes</quote> colorizes the given image.
The difference to blend is, that the brightness is preserved.
The <quote>factor</quote> attribute determines the ammount of
colorizing. Just try this effect, to see the result.
</para></listitem><listitem><para>
<quote>Scale</quote> scales the image to the size given by the
<quote>width</quote> and <quote>height</quote> attributes.
</para></listitem><listitem><para>
<quote>Crop</quote> crops the image. You give a
<quote>xoffset</quote> and <quote>yoffset</quote> and the
new <quote>width</quote> and <quote>heigh</quote>.
</para></listitem></itemizedlist>

</sect1>
