[
  This is a text version of the article 
  'Creating modules for Doodle's Screen Saver - Part 3' on EDM/2!

  The original can be found here:
  http://www.edm2.com/index.php/Creating_modules_for_Doodle%27s_Screen_Saver_-_Part_3
]

Introduction
------------

Starting with the v1.5 version of Doodle's Screen Saver, the package contains a
new module called 'Pretty Clock'. This screen saver module shows a skinnable 
clock on the screen.

The purpose of this article is to describe the format used for the skins, so
people might be able to create their own clock skins.


The basics
----------

The Pretty Clock module assembles its clock image from five different layers. 
All these layers are transparent PNG files. These layers are the following:

    * Background
    * Hour marker
    * Minute marker
    * Second marker
    * Foreground 

As you can imagine, a nice watch can be constructed using this method by 
putting the image of the watch to the background, putting the markers on top
of it, then putting another transparent image on top of these to imitate the
glass of the watch.


To Rotate Or Not To Rotate
--------------------------

Now, to make things a bit more flexible (and a bit more confusing), the drawing
of the markers have been made special.

Imagine, that you have an image of the hour marker, pointing to 12:00. If the
time is 06:00, then it has to be rotated by 180 degrees. However, if you want
your marker to be very nice, you draw shadows to it, but a rotated version of
this image will look ugly, because it will rotate the shadows, too.

So, it was decided that the skin designers can decide which statuses they want
to draw. It's possible to draw 24 different images for the hour marker, one for
each possible position of the marker. If the code finds an exact image for the
given hour, it will use that one, or it will find the closest match, rotate
that image, and use the rotated image.

The same applies to the minute and second markers. It's possible to have only
one image of them, then that image will be rotated. However, it's also possible
to draw all the possible positions of the markers, then those images will be
used.

It's also possible to draw only some of the positions of the markers, like 0,
15, 30 and 45 minutes, or any combination you like, the missing ones will be
created automatically by rotating the closest available image.

Simple, no?

Yes? Well, then here comes one more twirl.
As you might be aware, there are clocks where the hour and minute markers jump
from one position to another, and there are ones where they slowly advance the
next position as the time goes. This later case is called "analogue mode" in
Pretty Clock, and both the hour and the minute markers can be told to work in
analogue mode.


The skin descriptor file
------------------------

You may ask now how to describe all these to the screen saver module?
Well, all these are described in a simple text file, which has the extension of
".skn". You will already find some skin files installed in "Modules\PrClock"
subdirectory of the Doodle's Screen Saver home folder, now that's the place
where you should copy your own skins to install them.

And now let's see the keywords you can use in the skin file:

Skin name
- - - - -

A short description or the name of the skin can be told by using the keyword 
"Skin_Name". For example:

Skin_Name = Test skin by Doodle

Draw area
- - - - -

All the layers are drawn inside a so-called Draw Area. The draw area is a
rectangular drawing space, in which all drawing is done. This area is moved
around the screen as the screen saving goes, so your pretty clock will not be
burned into the monitor.

The size of the Draw Area can be told by using the following keywords:

Draw_Area_Width = 256
Draw_Area_Height = 256

The images
- - - - - -

All the images of the layers can be described by using two keywords for the
given image. The first one tells the PNG file to use, for example:

Background_Image = test\test_back.png

(All the file paths are relative to the place of the skin file.)

The second one tells the center of the image, so the module will know how to
rotate that image if needed. It's not used for the foreground and background
images, but it can be used for the markers:

Hour_0_Image = test\test_stick.png
Hour_0_Image_Center = 128 128 64 64

The four numbers are: <CenterOffsetX> <CenterOffsetY> <CenterX> <CenterY>

The CenterX and CenterY values tell the center of the PNG image. The image will
be rotated around this point, if it has to be rotated. Most of the times it's
the center of the image, but it can be set so that the image will be rotated 
around its bottom or anything else.

The CenterOffsetX and CenterOffsetY values tell a coordinate inside the Draw
Area, where the center of the image (given above) will be positioned. This is
usually the center of the Draw Area.

Please note that all coordinates are relative to top-left corner, which is 
(0;0).

The following images can be specified:

"Background_Image" and "Background_Image_Center"
"Foreground_Image" and "Foreground_Image_Center"
"Hour_0_Image", "Hour_1_Image" ... "Hour_23_Image" and the corresponding 
"Hour_0_Image_Center", "Hour_1_Image_Center" ... "Hour_23_Image_Center"
"Minute_0_Image", "Minute_1_Image" ... "Minute_59_Image" and the corresponding
"Minute_0_Image_Center", "Minute_1_Image_Center" ... "Minute_59_Image_Center"
"Second_0_Image", "Second_1_Image" ... "Second_59_Image" and the corresponding
"Second_0_Image_Center", "Second_1_Image_Center" ... "Second_59_Image_Center"

Analogue modes
- - - - - - - -

As it was already described, the hour and minute markers can work in 
"analogue mode", where they do not jump from one position to another, but
slowly advance it. This can be turned on and off by setting the value of the
following two keywords to 1 or 0:

Hour_Analogue_Mode = 1
Minute_Analogue_Mode = 1


Conclusion
----------

As you can see, creating new clock skins is not hard. You only need some
inspiration, some drawing tools, create your images, assemble your SKN file,
and you're done.

All you have to take care is to make sure that all your PNG files are
transparent! If a given PNG file is not transparent, it will not be loaded by
Pretty Clock, so your skin will either not be loaded at all, or some parts of
it will be missing.

Good luck with creating your new skins!

<End of document>

