StyleClock is an incomplete, but good looking replacement for the
regular KDE clock kicker applet. It is easy to create new themes,
and your are not limited to regular analog clocks.

copyright 2004-7-14 by Fred Schaettgen <styleclock.sch@ttgen.de>

For some short installation instructions, see the INSTALLATION file.

Once compiled and installed (and after restarting kicker), you can
add the clock to kicker like any other kicker applet.
StyleClock comes with several themes. You can select one by clicking
the little arrow on the applet handle and select "Configure styleclock.."

There you can change the theme and other stuff, like disabling the
second hand if it annoys you.

That's it regarding usage. Now for the more insteresting part:

Creating new themes
-------------------

StyleClock is bitmap based, and it will stay like that in the forseeable 
future. SVG is not an option at the moment for several reasons.
First, ksvg is not in kdelibs, second, it's doesn't seem to be usable
by other application.
Before you try to convince me to use SVG, you should make yourself clear
that scalability itself doesn't solve all the problems related with
scaling images. If your kicker is set to "Small", then there may be just
not enough pixels available to display a readable analog clock.
SVG may have many benefits, but it certainly doesn't solve all the problems
related to scaling icons (or clocks).

So what does a theme consist of?
A theme is simply a directory with some images (preferrably png) and 
a description what to do with these icons.
Since there are so many possiblities for how to draw a clock, like 
different options and kicker sizes, a theme places the images with
a little ECMA-Script (aka Javascript) program.

This script is called "main.js" and is evaluated every second.
If you feel a heart attack coming - it's not really that bad ;)
With javascript you only define, which image goes where (and how
much it is scaled, rotated etc.). Loading, tranforming and drawing 
of the images is done with good old C++. And since rotating images
in good quality is still an expensive opertation, OpenGL is used
for to draw the mipmapped images.

Here is an simple exmaple for how to draw a clock:

WARNING: Since this is _documentation_, chances are good that
this example is outdated. If it doesn't work, try looking
at the real theme scripts. And please tell me about the problem.

Also see README.scripting in the themes directory of the distribution

---------------Begin main.js -----------------

// (1)
lBG = defineLayer("bg.png");
lMinute = defineLayer("minute_hand.png");
lHour = defineLayer("hour_hand.png");

if (showSeconds) lSecond = defineLayer("second_hand.png");
else lSecond = new Object();

lFG = defineLayer("fg.png");

centerX = 0.515;
centerY = 0.485;
// (2)
scaleX = screenWidth;
scaleY = screenHeight;

// (3)
lFG.scaleX = lBG.scaleX = lHour.scaleX = 
    lMinute.scaleX = lSecond.scaleX = scaleX;
lFG.scaleY = lBG.scaleY = lHour.scaleY = 
    lMinute.scaleY = lSecond.scaleY = scaleY;
lHour.anchorX = lMinute.anchorX = lSecond.anchorX = centerX;
lHour.anchorY = lMinute.anchorY = lSecond.anchorY = centerY;

// (4)
lHour.rotate = hour*30+(minute/2);
lMinute.rotate = minute*6;
lSecond.rotate = second*6;

----------- End main.js ---------------------

(1) First you have to create the layers you final clock image will consist of.
Therefore you call "defineLayer()" with a filename as parameter and save
the result to some variable.
The filename is relative to the theme directory, so usually you will just
write the name of the file itself.
The order in which you create the layer is the final paint order.
But the images are not painted right away. First you have to chance to
change a few parameters.

(2) Since you have to scale and move your images depending on the size
available, there are several variables defined. The size availble to your
clock is stored in 'screenWidth'/'screenHeight'.

(3) The initial image position is (0,0) and the size of the image 
is (1,1) - just *ONE* pixel. So you have to scale it to be able to
see anything. 
To do this, each Layer object has some properties:
- moveX, moveY: Translation in pixels from the upper left corner
- anchorX, anchorY: used as a pivot point for rotating. 
  0,0 is the upper left corner of the image, 0.5/0.5 is the center etc.
- rotate: Roating *clockwise* in degrees. 
  We're programming a clock here, so this makes sense ;)
  
(4) The rotation depends on the current time, which is stored in the
variables 'second', 'minute' and 'hour'. hour is 0-23.

Installing new themes
---------------------
Now that you have your images and the controller script, put it into
a subdirectory and install it either to $(KDE_DATA_DIR)/styleclock/themes
This may be a systemwide directory or one in your home-directory.
You can get the list of valid data dirs with

kde-config --path data


