World Clock 1.0a by Dan Wilga
Copyright ½ 1995, Gribnif Software
All Rights Reserved.
This program may be distributed freely, provided it and this text file are
See the end of this file for the revision history.
This program is ChocolateWare. If you find it useful, you are encouraged
to show your appreciation by sending a quantity of chocolate candy to the
address below. What kind and how much are up to you. Please just limit
yourself to chocolate, either with or without nuts.
PO Box 779
Northampton, MA 01061
Too Much Time On My Hands
I often need to call someone in some remote corner of the globe (I've
always hated that expression because, as you probably know, globes don't
have corners) and I find myself wondering if I'm going to be calling at
some rediculously early (or late) time. Most of Europe is easy for me to
remember, but I've already found out that calling an Australian at 5:00 on
Saturday morning is not an acceptable thing to do.
I looked around and could not find a program that suited my needs: I wanted
a picture of the world, not just a text list of cities that are probably
nowhere near the place I really want to call. Of course, in order to keep
track of things accurately, a world clock also needs to have an idea about
daylight savings, and not just assume everyone uses the same method.
[Bored yet? If so, you can skip ahead to the next section. I would have
Well, I couldn't find anything that fit the bill, or even came close. So,
I set about creating my own program. The first thing was to find a map. OK,
that was the easy part. Next, I wanted it to be scalable to any size, so I
used Convector Professional to vectorize the map and save it as a GEM file.
Fortunately, the map I used employs what is probably the most common method
for stretching the continents so that the map of our spherical globe will
end up flat: it's called Mercator's Projection. Unfortunately, it took more
hours of research in the local library than I care to mention to find out
what the mathematical relationship between latitude and map location are
when using this projection. But I finally found a simple formula.
Along the way, I also came across an invaluable book called "The
International Atlas" (see the bibliography at the end of this file), which
not only gives the coordinates of thousands of cities in the world, but
also gives very precise information about how each country (and even each
region within the country) handles daylight savings.
Now I just had to write a program to display the map in a useful way, and
pop a list of cities into a text file. World Clock is the result.
Setting it Up
World Clock works as a program or a desk accessory. It works in any
resolution, and probably with any graphics card. It also works with
multitasking environments like Geneva, MultiTOS, and MagiC.
To run it as a program, these files are necessary:
WORLDCLK.RSC Resource file
WORLDCLK.DAT Data file with cities and other preferences
WORLDCLK.GEM The map
There is also a second map called DETAILED.GEM. You can use this in place
of WORLDCLK.GEM by renaming WORLDCLK.GEM to something else (like
LOWREZ.GEM) and then renaming DETAILED.GEM to WORLDCLK.GEM. The
disadvantage to DETAILED.GEM is that it takes more memory to load (just
look at the difference in the file sizes) and whenever the window redraws,
it may redraw more slowly depending on your setup.
To run it as a desk accessory, you would simply rename WORLDCLK.PRG to
WORLDCLK.ACC and put it (along with the other files) in the same directory
as all your other desk accessories.
In order to prevent too much clutter, you can also put everything but the
WORLDCLK.ACC file into a folder called WORLDCLK. For instance, if your desk
accessories load from C:, you would put WORLDCLK.ACC in C:\, and put the
rest of the files in a folder called C:\WORLDCLK\.
The only functional difference between using World Clock as a desk
accessory versus using it as a program is that when used as a desk
accessory, World Clock will only allow you to add 10 places to the list in
Once World Clock is running, there is one thing you need to do in order to
configure it for the first time:
Before World Clock can be of any real use to you, you need to tell it where
you live. Do this by clicking on the "?" icon in the lower right of the
window. This will give you a popup menu. Select the "Edit Places" option.
In the "Edit Places" dialog, you will see that some information about the
various places World Clock knows about by default. What you need to do is
choose a place which is in the same time zone as you currently are, and
uses the same method for daylight savings.
Scroll though the list of places by using the "+" and "-" buttons next to
the name of the current place. Don't worry if you live in Florida and the
closest thing you can find is New York. That's good enough for now.
To help you find a place which is close to you, here is a West to East
list of some of the cities, presented by region:
USA: Honolulu, HI Anchorage, AK
Los Angeles, CA Denver, CO
Dallas, TX Chicago, IL
Indianapolis, IN New York, NY
Canada: Vancouver, BC Edmonton, AB
Toronto, ON Montr‚al, QC
Halifax, NS St. John's, NF
Europe: Reykjav¡k Belfast
Amsterdam Roma (Rome)
Berlin Athinai (Athens)
Helsingfors (Helsinki) Kijev
Moskva (Moscow) Volgograd (Stalingrad)
Australia: Perth Adelaide
When you have found a place that is in the same time zone and uses the same
emthod for daylight savings, select the "Here" button. This indicates that
the place you chose should be used for computing other times in the world.
When finished, select the "Done" button.
If you can't find a place which is close to where you are, refer to the
section about the "Edit Places" dialog, for more information on how to add
new places to the list.
Now it gets interesting. On the map you will notice that a number of
locations have either a diamond (on a monochrome monitor) or a red plus
sign (on a color monitor). If you move the mouse arrow over one of these
markers and press the left mouse button, a dialog will pop up and tell you
what time it is in that place. If you either let go of the mouse or drag
the pointer away from a place, the popup will disappear.
More Features in the Main Window
As you move the mouse around the main window with the left mouse button
pressed, you may also notice a coordinate display in the lower right of the
window. This tells you the latitude and longitude the mouse pointer is
currently at, and gets updated as long as the mouse button is pressed.
This feature can be turned off in the "Options" dialog (see below).
By default, World Clock shows the local time in the mover bar of the
window. This can be turned off in the "Options" dialog, as well.
To conserve screen space, World Clock uses two icons in the lower right
corner of its window. You've already seen what the "?" gadget does (it
gives you a menu of choices), now it's time for you to try the resize
gadget to the far right.
To resize the window, grab the resize gadget and drag the outline which
appears. You will notice that the horizontal and vertical directions always
stay in a constant ratio. This is so that the map will not look distorted.
When you let go of the mouse, the map will redraw at the new size.
The Popup Menu
The popup menu, which is accessed by clicking on the "?" gadget in the
lower right of the window, contains several options:
o am/pm or 24-hour mode affects how time is displayed in the popup
which appears next to a place, in the local time, and in the hours
display. By default, World Clock tries to read an "_IDT" system
"cookie" to determine whether 24-hour time is preferable for your
o Show Day in Popup controls whether or not the place popup will
contain an extra line which describes whether time at the place the
mouse is over is "Yesterday", "Today", or "Tomorrow".
o Show Hours gives you a bar at the top of the main window which
contains the relative time at even increments along the map. Of
course, many places differ from this number, but it is useful as a
reference. Note that if the window is too small, some or all of the
hours may not be visible because they do not fit.
o Show Coordinates, as stated before, controls whether or not the
latitude and longitude of the current map location will be displayed
when the left mouse button is pressed in the main window.
o Show Current Time controls the display of local time in the window's
This is probably the most important dialog. As you've seen already, it
can be used to look at the list of places that World Clock is
displaying. It also lets you enter new places and edit existing ones.
At the top of the dialog is the name of the current place. There are
also "+" and "-" button which will cycle through the list of places.
Below the name is where the longitude and latitude of the place can be
changed. All coordinates are listed in degrees and minutes (60ths of a
degree). This means that the largest number that can appear in the
minutes section of a coordinate is 59. If you enter an incorrect value,
you will be prompted to correct the error.
Longitudes can either be east ("E") or west ("W") of 0 degrees, so you
should select the appropriate button when entering a new coordinate.
Otherwise, the marker for the place will not appear in the correct
location. Latitudes can either be north ("N") or south ("S") of the
equator. You can usually find the coordinates of a place by using an
atlas or map. It is not necessary to be too accurate, unless you use
World Clock with the main window at a large scale.
Underneath the coordinates you should enter the number of hours and
minutes that the local time of the place differs from Greenwich Mean
Time (GMT). For example, New York is 5 hours 0 minutes to the West of
Below this is where you can choose the type of daylight savings used at
the place. When World Clock notices that the current day and time fall
within the times of the year that daylight savings is present, one hour
will be added to the local time of the place when it is displayed. If
you are unsure what daylight savings method a particular place uses,
you can just select "" from the popup and no adjustment will be
made. See the "WORLDCLK.DAT Format" section for information about how
to add more daylight savings entries to the list.
The "Attributes" section provides you with two options:
o Here: In order for World Clock to be able to calculate the times of
other places, it needs to know where you are located now. You
can only select the "Here" button of one place in the list. Choose
a place which is at least in the same time zone that you are in,
and preferably one that uses the same method for daylight savings.
o Show Marker: When this button is selected, a marker will be shown
at the coordinates of the place on the main map window. Turning the
marker off for a particular place can often help to make other
markers more visible when they are tightly packed together.
The list of cities can be sorted in one of three ways, either alphabet-
ically by name, in a north to south direction, or in an east to west
direction based on coordinates.
The "New" button will add a new, blank place to the list. You must then
edit the various parts of the place's description. When using World
Clock as a desk accessory you are only allowed to add 10 places to the
list in one session. You must "Save Settings" and reboot the computer
in order to add more places. When using World Clock as a program, you
can add as many places to the list in one session as memory permits.
To remove the current place from the list, use the "Delete" button.
Deleted places cannot be recovered, so use this button carefully.
"Go To" will complete any changes you have made to the list, and return
you to the main window. You will then be shown the location on the map
of the place you were last looking at in the "Edit Places" dialog.
The "Done" button completes changes to the list and returns you to the
main window. If you have made any changes to the list when you quit
World Clock, you will be prompted to save the changes before quitting.
Note that you will only get this prompt if you are using World Clock as
a program, not a desk accessory.
This feature allows you to change your system clock's date and time.
The _IDT cookie is used here, too, to determine what order the month,
day, and year are displayed in the date.
This saves all configurable options, including the window size and
position, and the list of places to WORLDCLK.DAT. If a change has been
made to the list of places when you quit World Clock, you will be asked
to save the changes.
This dialog gives information about the version of World Clock you are
Many locations change their method of daylight savings every few years.
For instance, the USA changed their start to the first Sunday in April
just a few years ago, and many older references on this subject are
still not updated. If you find that one of the default cities is
incorrect, please let me know at the address above and I will correct it
in a future version.
This section describes the format of WORLDCLK.DAT. You do not need to
read this section unless you either want to add a large number of places
without using the "Edit Places" dialog, or you need to add more daylight
The file is a regular ASCII text file. Any line beginning with a * can be
in any order. The commands which follow a * can be one of these:
*Window Window x, y, width, height
*Sort 0=Name, 1=N->S, 2=W->E
*am_pm am/pm or 24-hour time
*DispCoords Display mouse coordinates
*DispDay Show "Yesterday", "Today", "Tomorrow" in popup
*DispHours Show relative time at top of window
*DispTime Show current time in mover bar
*Daylight A description of daylight savings:
---- start savings ---- ----- end savings -----
index hour which month day hour which month day change name
index: a letter (case is unimportant) to be used in the flags field of
places that use this method of daylight savings
start savings: the day and time at which daylight savings begins
hour: hour of the day, in 24-hour format
which: if 0, then "day" is the date of the month when the change
takes place, regardless of weekday. For instance, if
"which" is 0 and "day" is 10, then the change occurs on
if >0, then "day" is the day of the week of the change occurs
on, where Sunday is 0. When "which" is 1, that means the
first "day" of the month, 2 means the second "day" f the
month, etc. See the examples below.
if <0, then it indicates the last "day" of the month (-1), the
next-to-last (-2), etc.
month: the month of the change, where 1=January
day: see description of "which"
end savings: the day and time at which daylight savings ends. In the
northern hemisphere, this is usually later in the year than the
starting date. In the southern hemisphere, like in Australia, it is
change: the number of hours of offset from GMT during daylight savings. This
is most likely
name: up to 16 characters
i h w m d h w m d c
i 2 -1 4 0 2 -1 10 0 -1 Canada
Daylight savings starts at 02:00 on the last Sunday in April.
It ends at 02:00 on the last Sunday in October.
i h w m d h w m d c
a 2 -1 10 0 2 1 3 0 -1 Australia
Daylight savings starts at 02:00 on the last Sunday in October.
It ends at 02:00 on the first Sunday in March.
i h w m d h w m d c
k 0 0 4 1 0 0 10 1 -1 Former Soviet
Daylight savings starts at 00:00 on April 1.
It ends at 00:00 on October 1.
Any lines not beginning with * are assumed to be places. These lines have
offset flags latitude longitude name
offset: the hours offset from GMT during standard time. Locations that
are East of GMT have a negative offset.
the first flag is "a" if the a marker for the place is visible
("active"), otherwise it is a "-"
the second flag is "h" if the place was chosen as "Here".
the third flag is a daylight savings index, or "-" if none.
latitude, longitude: these are in the format "degrees.minutes". A
negative latitude is south of the equator, and a negative longitude
is west of the prime meridian.
name: up to 27 characters
"The International Atlas, World Latitudes, Longitudes and Time Changes",
Thomas G. Shanks, ACS Publications, Inc., San Diego, 1985.
It will no longer crash when loaded on a machine that does not have a
cookie jar (like TOS 1.0 or 1.2).
If you run it without a WORLDCLK.DAT, entering the Edit Places dialog
to add new places now works.
12pm is now displyaed properly in the time that appears in the window's