Tock User Guide

A Desktop Clock

v0.03 22^nd September 2004

v0.04 13^th February 2022, 64k colour mode support, recompiled for ARM v8

Operation

This is a somewhat 'over the top' clock, but is rather good fun. You can thank or blame the lack of watchable tv programs for its creation.

There are no special requirements other than it probably needs at least RISCOS 3.5.

Set the time using the !Alarm program.
Select the clock face from the menu list.
Adjust the display size by dragging the bottom right corner.
When the Title bar is switched off, the normal title bar functions are simulated along the top margin of the clock window.
The clock window can be moved by dragging anywhere within the window area except where any simulated window control buttons are located.

Sit back and watch, in the knowledge that far too much of your memory and processing power is being used to tell you you're wasting time.

Display colour depths of 256, 32 thousand, and 16 million are supported.

Clock window menu

This provides the following facilities.

Face:	Select a clock face.
Chime/Strike:	These will be greyed out and unavailable until Chime/Strike files have been created or installed. Click select to switch on or off the currently selected chime/strike type. Open the sub menu to select a type of chime/strike.
Options > Chime/Strike check:	These will also be greyed out and unavailable until Chime/Strike files have been created or installed. Open the sub menu and click select to try the currently selected chime/strike.
Options > Title bar:	Switches the clock window title bar on or off.
Options > Window border:	Switches the window border on or off. This only has effect when the title bar is switched off
Options > Iconbar icon:	Switches the iconbar icon on or off. When turned off, the clock window close icon quits the program.
Options > Update period:	This specifies the the minimum time between clock window redraws. It can be increased to reduce processor loading. The default of 200ms works well for clock faces with second hands. A face without a second hand does not require updating so often. A long update period will affect the accuracy of a second hand and also the timing of chimes and hour strikes.
Help:	Open the help file.
Quit:	The current choices are saved on exit.

Chimes and Hour Strikes

The application is supplied with chimes and hour strikes disabled. To enable them, select "Make Chimes..." from the iconbar menu. This opens a window from which a set of audio files can be created. These files are noticed by !Tock next time it is run, enabling the Chime and Strike menu items. About 19Mb of disc space is required.

The resulting audio files are simply run by !Tock when required. For this to work you must have a means for running them installed, e.g. !PlayIt for the audio files created by MakeChimes.

The files need not be wav audio and could be MP3 or even Obey files. If the Filer knows how to run them it should work. No checks are made by Tock.

Inside every Chime directory is a file called Pretrigger. This tells Tock how many seconds to start the hour chime in advance so that it finishes in time for the hour strike to be started exactly on the hour. If the file is not there, the previous value is used or 20 seconds if no previous value is known. The maximum value for pretrigger is 599 seconds.

The Make Chimes facility uses a text file to define what to make. If you wish to create your own, read the notes at the start of the file "Default" in the "Data.Scripts" directory.

PlayIt needs to be loaded and set to play wav files. This is performed in the !Tock.!Run file. If you do not want to use PlayIt, comment the line that runs the Obey file LoadPlayIt.

Creating Clock Faces

The displayed frame is built up by plotting sprites in layers. The sprites are contained in the Sprites file in a clock face directory. If a sprite has a mask, it will be plotted using it. The sprites are rotated before plotting in accordance with the information read from the Rules file in the clock face directory, and the current local time. The display is updated once a second.

A maximum of 10 sprites or layers can be defined per clock face. All sprites of a clock face must be the same size, either 256x256 or 128x128 pixels, but can be a mix of 256, 32 thousand, or 16 million colours. They need not be the same colour depth as the display, but less memory is used if they are. Use the desktop palette for 256 colour sprites.

The Rules file is a text file containing a list of sprite layer definitions. Each line defines a single layer as follows.

name name of sprite in Sprites file
resolution number of seconds between each rotation increment
increments number of increments per revolution
offset fixed angular offset

e.g.

   
    # example
    # name      res   inc  offset
    background    0     0     0
    hours        60   720     0
    minutes       1  3600     0
    seconds       1    60     0
    cover         0     0     0

Blank lines and lines starting with # are ignored.
Fields are space separated.
The example file above is interpreted as follows.

Plot sprite "background" with no rotation.
Then plot sprite "hours" at 1 rev. in 12 hours. 1 minute resolution
Then plot sprite "minutes" at 1 rev. in 1 hour. 1 second resolution
Then plot sprite "seconds" at 1 rev. in 1 minute. 1 second resolution
Then plot sprite "cover" with no rotation.

Sprite "background" has no mask, the rest have masks.
Sprite "cover" is required to hide mirror images of the rotating hands in the corners caused by the rotation functions.

The resolution field is in seconds. A resolution of zero produces no rotation. A negative resolution produces anticlockwise rotation.

The rotation angle accuracy is 0.1 degree so there is no point in making the number of increments more than 3600. The maths will overflow when the number of increments exceeds 596523.

The offset field produces a fixed rotation in addition to timekeeping. It is provided so that sprites of hour, minute, and second hands need not be pointing to 12 o'clock. The offset can be signed and is in units of 0.1 degrees. i.e. 3600 is a complete revolution. If your minute hand sprite pointed to 10 o'clock, the required offset would be 600.

A seven day seconds counter is used, making it possible to have an indication of the day of the week.
e.g.

  day   86400 7 0

An AM/PM layer would be,

  am_pm 43200 2 0

Pete Everett
contact: peverett33@gmail.com

name	name of sprite in Sprites file
resolution	number of seconds between each rotation increment
increments	number of increments per revolution
offset	fixed angular offset