Help Text for RISC OS MoonTool

RISC OS MoonTool, Version 3.26.
Last modified: 27.09.99





MoonTool is a desktop application that calculates and displays the current phase of the moon and other related information.

The original version of the program was called "A Moon For The Sun" since it was written for Sun workstations. Sometime around 1993 Eduoard Poor ported MoonTool to RISC OS 3.

Later, in early 1999, I saw a request for the moon to appear the right way up in the program (Eduoard was based in New Zealand so naturally the moon drawn by his version was the wrong way up for those of us in the Northern hemisphere). Also requested was the ability to calculate the moon phase/information for times other than the current date/time. Since both these things had been on my list of "Things to get around to one day" I decided I'd finally get on and do them.

Note that for MoonTool to work correctly the clock in your computer must be set correctly and your TimeZone/DST must also be correct. See your RISC OS user guide for more information.

MoonTool is compatible with RISC OS 3.1 and later.


Using MoonTool

MoonTool is run in the normal RISC OS fashion (ie. double-click on its icon in a filer directory display). There's no reason why you shouldn't include MoonTool in a boot sequence (eg. in !Boot.Choices.Boot.Tasks on RiscPCs) if you're the sort of person who likes having the moon on your desktop to keep you company. I know that I do.

Initially a small window will open that displays a picture of the moon as it appears in the sky (although it is always shown upright). Clicking on the moon in this small 'icon' window will open the main window which contains various pieces of information about the date and relative positions of the sun, moon and earth. Closing the window, or clicking Select on the Moon graphic, will cause the smaller 'icon' window to be re-opened.


Moon phases

Selecting "Moon phases..." from the menu will open a window containing the dates and times of the quarters of the moon surrounding the currently selected date/time. The dates/times shown are all in UTC (Universal Time Coordinated), ie. GMT.

You can also open/close the Moon phases window by clicking with Adjust on the Moon icon or the Moon in the main MoonTool window.


Gamma correction

If you find that the Moon graphics are too bright or dark on your monitor, you can adjust their 'brightness' using the Gamma Correction option from the main menu.

In the Gamma Correction window, there is a small image showing two grey-scales and the Moon at both full and new phases. Between the grey-scales is a line of alternate blocks of solid grey and 'dithered' grey. Ideally, these blocks should look as close to each other in 'brightness' as possible.

To save the gamma correction setting, use Save choices from the main menu.


Saving the window positions, etc.

You can save the gamma correction setting and current positions of the various windows by selecting Save choices from the main menu.

When MoonTool is next reloaded it will initially open the windows in the same place they were when the positions were saved.

If you want to "clear out" these saved positions you can do so by deleting the text file !MoonTool.WinPosns.


Selecting a different time/date

If you select "Choose time..." from the menu a window will open that allows you to select the date and time of day that you want MoonTool to use for its calculations.

Note that whilst test-mode is active the Choose Time window will not work as expected. Rather than following the time selected test mode will simply 'step' each time a change is made. It's probably best not to mix the two.

The window contains a number of icons:

When this option is selected, MoonTool will use the current date and time (as obtained from your computer's clock) and update its display(s) in real time.
The time adjustment icons will be shaded and un-selectable whilst this option is selected.
Note that this option doesn't have an immediate effect. You must click on the "Use" button to cause MoonTool to effect it.
This option, when selected, causes MoonTool to update its displays in line with the time showing in the time selection window.
It can sometimes be useful (especially on older/slower machines) to turn this option off when selecting a time as the calculations MoonTool performs are relatively time consuming and so slow things down.
Note that this option takes immediate effect - you don't need to click on "Use".
Bump arrows
Use these arrows to select the date and time of day you're interested in. If you've ticked "Update" then MoonTool's various displays will be updated as the values are changed.
Clicking this button causes the current date and time to be entered into the time selection window.
Resets whatever options were in force when the time selection window was opened. If the button is clicked with Select then the window will also be closed. Clicking with Adjust keeps the window open.
Causes MoonTool to use the options (or time/date) in the window. As with "Cancel", clicking with Adjust rather than Select will cause the window to stay open on the screen.


Test Mode

The original MoonTool had a 'test mode' that rapidly stepped through time. Later versions (for the Sun/X11) added a button to (dis)engage this feature at any time. I've added this feature to my RISC OS version as a menu option and extended it to allow three different test speeds.

If you select "Test mode" from the menu then test mode will be engaged at the last selected speed ('Slow' initially). When test mode is engaged it can be cancelled either by reselecting it from the menu, or by selecting "Off" from the Test Mode submenu.

You can simultaneously engage test mode and select a speed by selecting one from the Test Mode submenu. The three speeds are (very approximately):



The original RISC OS version of MoonTool was quit by closing its main window. This version should be quit by selecting "Quit" from its menu (or by quitting it from the Task Manager's Tasks display, etc).



There are a few user selectable options that can be set by editing the application's !Run file.

The options are:

Start up 'iconified': -i
This is set as standard. If for some reason you want MoonTool to open its main window at startup (rather than the little 'icon' window) then removing the -i from the !Run file will make this happen.
Conversely, replacing the -i will cause MoonTool to open the small 'icon' window rather than the main window at startup.
Hemisphere: -n or -s
You can select either Northern or Southern hemisphere in the !Run file by including the flags -n or -s as appropriate.
By default, MoonTool assumes Northern hemisphere.
Open phases window at startup: -p
This flag will cause MoonTool to open the moon phases window at start-up.
Start in test mode -t
This flag causes MoonTool to start up in test mode (at the default, ie. slow, speed).
Use outline fonts in the windows: -o
This flag causes MoonTool to use outline fonts in its windows. Depending on the machine and monitor/screen-mode combination you are using you may find that outline fonts improve/reduce readability.
Brighten text in the windows: -b
You may find, especially at large screen sizes, that the grey-on-black text in the MoonTool windows is too hard to read. The -b option causes MoonTool to display all text (that has a black background) in white rather than grey.



To the best of my knowledge the dates and times given by MoonTool are reasonably accurate. The original documentation (which is included verbatim as !MoonTool.!HelpOrig) says that the times should be accurate to within 10 minutes.

If you feel like checking up on MoonTool there are tables of moon phases, etc. available on the 'net, for example:


Differences between the RISC OS version and the original

I've substantially changed the part of MoonTool that determines the times of the new moons surrounding a given date (and from these the times of the quarters in between). This was necessary since the original method could produce incorrect results, especially when using the time selection window.

The "ghost moon" drawing is my own interpretation of how this should be done. I believe that the Sun/X11 versions have an option to use colour or monochrome when drawing the moon and show the dark area of the moon in blue. I haven't bothered with the monochrome option (it doesn't really seem worth it...) and chosen to make the dark moon look dark. If you really do want it to be blue, this is possible (see below in the "techie" section).

The Moon sprites used were obtained by scaling down a rather nice picture of the full moon I obtained from a PD source some years ago.


Technical details

The full source code is available as a separate archive. It should be available from the same place as MoonTool itself, or failing that from my web pages, or failing that drop me an e-mail.

It's possible to change the way that the dark moon is drawn by editing MoonTool's Messages (and possibly Sprites) files. Specifically, the Messages file contains the definition of the pixel translation table used to darken pixels in the sprite.

It should also now be possible to create a version of MoonTool for a different language without having to re-compile. The Messages and Templates files should now contain all the language specific words/phrases.


History (of my versions)

3.26 (27 Sep 1999)
3.25 (28 Apr 1999)
3.24 (05 Apr 1999)
3.11 (16 Mar 1999)
3.10 (24 Feb 1999)
2.00 (19 Feb 1999)



Designed and implemented by John Walker in December 1987.
Revised and updated in February of 1988.
Revised and updated again in June of 1988 by Ron Hitchens.
Revised and updated yet again in July/August of 1989 by Ron Hitchens.

Original RISC OS port by Edouard Poor, circa 1993.
This RISC OS port by Musus Umbra, 1999.

RISC OS MoonTool was built using DeskLib (the freeware desktop C library for RISC OS machines).

I'd like to thank the following people for variously suggesting improvements, offering advice and prompting me to update the program in the first place: Alan Gray, Reg Hemms, Raymond Ling, Michael Rozdoba, Graham Jenkins, Fionn Taylor & Matthew Somerville.



This program is in the public domain: "Do what thou wilt shall be the whole of the law".

Please leave the original attribution information intact so that credit and blame may be properly apportioned.



The authors cannot and will not be held responsible for any loss or damage arising from the use of, misuse of, or inability to use this software.

I am, however, interested in bug reports and feedback and will do my best to help if you do have problems.


Contact details

Musus Umbra, aka Adny: e-mail:
snail: c/o 23 Baronsway, Whitkirk, Leeds 15, LS15 7AW, ENGLAND