JFW Time Zone Scripts
Version 1.0 (4/9/2001)
By Andrew Hart

Development History:
4/9/2001:  Release version 1.0 of JFW Time zone Scripts
12/3/2001:  Inception and development commenced.

SYSTEM REQUIREMENTS:
Known to work with JFW version 3.31 and later.
May function with versions 3.2.x and 3.3.x, but this has not been verified.
Will definitely not work with versions earlier than those listed above.

DEPENDENCIES:
Requires clock.dll to be installed and registered in 
the Windows Registry.

SYNOPSIS:
This set of scripts allows Jaws for Windows to announce the current time in any one of 64 user-
selectable time zones.

INSTALLATION:
This installation is a little tedious at the moment, but I hope you'll find your effort well-
rewarded once the scripts are installed on your system.  I am investigating ways of automating 
this process.  The scripts are installed directly into the JFW default scripts, which means that no matter what you are 
doing, you can always check out the current time elsewhere in the world with one quick keystroke combination.

To install the scripts, do the following:

1.  Using Winzip or some other unzip utility, extract all the files from the .zip archive into 
an empty directory on your hard disk.  You should have the following files:

. readme.txt:  this file
. jfwtz.jss:  The JFW Time Zone Script source code
. jfwtz.jsd:  JFW help documentation for the time zone scripts
. clock.dll:  ActiveX DLL providing all the time zone functionality to JFW

2.  Copy the clock.dll file into your Windows system directory and 
register it in the Windows registry.

To do this, copy the clock.dll file into your c:\windows\system (Windows 95/98/ME) or 
c:\winnt\system32 (Windows NT/2000) directory.  Note, for Windows NT/2000 users, you will probably require administrative 
access in order to do this.  Then, bring up the context menu by either pressing
the context key or right-clicking on the clock.dll icon.  Then choose open.  If you are asked 
which program to open it with, instruct Windows to use c:\windows\system\regsvr32.exe in Windows 
95/98/ME or simply regsvr32exe in Windows NT/2000.

3.  Make a backup of your default.jss and default.jsd files which are located in your JFW settings\enu directory.  For 
example, if you are using JFW 3.5, you will find default.jss in c:\jfw35\settings\enu.
In fact, It is a good idea to have a complete backup of your JFW settings\enu directory.  

4.  Run the JFW Script Manager by pressing Insert-0 (zero on the main keyboard) and open the 
default.jss file by pressing Ctrl-Shift-d.  Then, copy and paste the contents of the jfwtz.jss file to 
the end of your default.jss file.  Press Ctrl-s to save and compile the file.  It should compile 
correctly.  

5.  Next, open default.jsd.  You can do this by pressing Ctrl-o to bring up the open file dialogue and then typing 
"default.jsd" followed by the enter key.  alternatively, you may select the file from the file list in the open dialogue.  
Note that if you prefer to browse through the list of files for default.jsd, then you will need to change the file type to 
"Documentation Files (*.jsd)", since the Script Manager defaults to "Source Files (*.jss)".  Copy and paste jfwtz.jsd to the 
end of default.jsd and save it.

6.  Close the JFW Script Manager by pressing Alt-F4.

7.  Run the JFW keyboard management utility by pressing Insert-8 (8 on the main keyboard).  Once the Keyboard Manager is 
open, press Ctrl-shift-d to select the JFW default script keyboard mappings.  Then press Tab to view the list of default 
scripts.  You need to reassign the Insert-F12 key combination from the SaySystemTime script to the SayTzTime script.  To do 
this, search down the list (using the arrow keys or page-down/page-up keys) until you reach SayTzTime.  Once there, press 
Ctrl-a to assign a key to the script.  A dialogue box will appear.  Simply press Insert-F12.  Next, the Keyboard Manager 
will complain that this key combination is already assigned to the SaySystemTime script.  Ignore this message and instruct 
the keyboard manager to continue anyway by selecting the "Ok" button.  Next, select "Ok" in the "Add Key" dialogue box to 
affect the key assignment.  You will be asked if you want to save the changes you have made to default.jkm and you must 
answer "Yes" to this.  Then you will be returned to the list of default scripts.
 Next, assign Insert-Shift-F12 to SayJFWTZScriptsVersion and Ctrl-Insert-z to the SetTimeZone 
 script in the same way as just  described.  Finally, press Alt-F4 to close the JFW Keyboard 
 Manager.

If you don't like the key assignments I have suggested here, feel free to change them.  However, I would recommend reassigning Insert-F12 to the SayTzTime script as this keeps all the time announcement functions in one place while remaining consistent with the standard JFW key bindings.

8.  Check the scripts and DLL versions by pressing Insert-Shift-F12.  You should hear "JFW Time 
Zone Scripts Version 1.0 utilising clock.dll Version 1.0".

Phew!  That's it.  It's installed and ready to go.

DEINSTALLATION:

Deinstallation involves reversing all the steps taken during installation.  Briefly, you must do the following:

1.  In the JFW Keyboard Manager, delete the key assignments to SayTzTime, SetTimeZone and SayJFWTzScriptsVersion, and assign 
Insert-F12 to the SaySystemTime script.

2.  Copy your backups of default.jss and default.jsd over their corresponding files.  Afterwards, open the JFW Script 
Manager by pressing Insert-0.  Then press Ctrl-Shift-d to load default.jss, press Ctrl-s to save and recompile the 
default scripts without the time zone functionality, and then close the Script Manager by pressing Alt-F4.

3.  Unregister clock.dll and delete it from the system subdirectory of your Windows root directory.  Note:  if you have used 
the time zone scripts since starting JFW for your current session at the computer, Windows will have locked the clock.dll 
file, believing it still to be in use by the JFW application.  This is actually incorrect, as the DLL is only in use when 
you execute one of the functions provided by the JFW Time Zone Scripts, but JFW refuses to let it go.  Nevertheless, Windows 
will not let you delete the file until JFW frees the DLL.  To do this, you merely have to shut down JFW and re-start it 
again.  When JFW stops running, it releases it's lock on the DLL and Windows is then free to unlock the file.

To unregister the DLL, go to the Run dialogue off the Start menu.  In the edit field, type

c:\windows\system\regsvr32.exe /u c:\windows\system\clock.dll

and press enter.  Note, Windows NT/2000 users will need to substitute "winnt" for "windows" and "system32" for "system" both 
times in the line above.  A dialogue box should appear indicating that the DLL was successfully unregistered.  Then simply 
use Windows Explorer to delete clock.dll from your system.

USAGE:
If the scripts are installed as per the directions above, you should be able to do the 
following:

Press Insert-Shift-F12 to hear the version of the JFW Time Zone Scripts and the installed DLL.

Press Insert-F12 to here the local time according to the current Windows time zone settings.

Press Insert-F12 twice quickly to here the current local date.

Press Insert-F12 three times quickly to here the current time in the selected time zone.  The 
time will be announced using the 24-hour clock, together with the name of the standard/daylight 
time operating in the currently selected time zone.

Press Insert-F12 four times quickly to here the date and time in the currently selected time 
zone.

Press Ctrl-Insert-z and JFW will bring up a list box containing a list of all the time zones for 
which it is able to report the current time.  It also takes into account whether or not 
daylight saving time is in effect in the selected time zone.  You will be able to tell if it is 
when the time is announced.  The first entry in the list indicates the currently active time 
zone.  Choosing it or pressing the Escape key will leave the currently active time zone unchanged.
The scripts default to UTC (universal time coordinated ) each time JFW is started.

KNOWN BUGS:
. None at time of release.

REPORTING BUGS:
If you find any bugs, please let me know by E-mail at andrew@jfwscripts.cjb.net.  In particular, 
it may be the case that the daylight savings information in the clock.dll database may not be 
correct.  Government's are continually tinkering with the rules for daylight savings time.  
However, the database is current to the best of my knowledge at the moment.

THINGS TO DO:
. Automate the installation process.
. Document the interface to clock.dll.
. Add a function to clock.dll to allow for a time and date in one time zone to be translated into another user-specified 
time zone.
. If there is sufficient interest, attempt to incorporate the public TZ database into clock.dll which would allow users to 
select a time zone by choosing their city or a city close to them.

ACKNOWLEDGEMENTS:
I must give credit to David Truong for getting me interested in developing these scripts.  When he first expressed to me 
his desire for some scripts that could announce UTC time for his work on ACB Radio, I hacked up some pretty primative 
scripts which required the user to callobrate them for there local time zone.  These scripts constitute a significant 
improvement over that initial attempt.  With the addition of the clock.dll, these new scripts can figure out all the time 
zone information without the user's assistance.  So long as the Windows system clock is correctly set, these scripts will 
render the current time in the desired time zone.  David also tested the scripts under Windows 98 for me.  Also, I must 
thank Glen Sepke for his "Screen Reader Extender" idea, which provided a nicely documented example of how to interface the 
JFW scripting language with COM objects.  Finally, my thanks go to Adrian Beech and Aaron Howell who tested the scripts 
under Windows 2000.  As always, any remaining bugs are not their fault.

DISCLAIMER:
Of course, the usual disclaimer applies:  use at own risk and I take no 
responsibility for anything that goes wrong while using these scripts, blah blah 
blah. In addition, feel free to use these scripts for anything you like, 
although occasionally crediting me as the creator would be appreciated and help 
to bolster the ego.  :-)
  