----------------------------------------------------------------
-----------------------  Visible Clock  ------------------------
----------------------------------------------------------------
                  ---      Version 2       ---
                  ---     4 April 1998     ---

       Copyright (c) 1995, 1996, 1997, 1998 by Eugene Dorr,
                      All rights reserved.

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

Visible Clock is an HP-200LX system-manager-compliant
application which displays the time of day in characters large
enough to see without squinting. It's handy for those times when
you wish you had a clock, but all you have is your handy
HP-200LX. Visible clock can also be an audible clock if you 
want: you can set it to chime on the hour or quarter-hour. In 
addition to displaying the current time of day in very big
characters, you can also use it as a stopwatch or a timer, and
see elapsed or remaining time in the same very big characters.

Because VClock is "system-manager compliant" it can be started
and used along with all other system-manager compliant applica-
tions, including other add-in system-manager applications. You 
can switch between these applications without quitting any of 
them, and when you return to an application, you are returned
right where you were when you left.

VClock is freeware. You may freely use it, copy it, and
distribute it. You may not charge for it, nor alter the
archive file.


---            ---
---  Manifest  ---
---            ---

The files included in this archive are:

    vclock.txt      This documentation file
    vclock.exm      The VClock executable
    vclock.icn      An Application Manager icon for VClock
    vclock.cfg      VClock configuration file
    timeball.icn    An alternate icon file
    timeball.txt    An explanation of the timeball icon


---                     ---
---  Installing VClock  ---
---                     ---

---  Step 1: Load the files  ---

Copy the following files to your HP 200 (They must both be
copied to the same subdirectory):

                        vclock.exm
                        vclock.icn

Copy the following file to your HP 200, into the C:\_DAT
subdirectory:
                        vclock.cfg

This file is optional, and only needed if you want to define
custom chime sounds.

---  Step 2: Define VClock to Application Manager  ---

Open Application Manager by pressing the [&...] key. Press F2
(Add), and enter the following values:

    Name:     Visible Clock
    Path:     (drive):\(subdirectory)\vclock.exm
    Comments:

In the Path field, (drive) and (subdirectory) should be replaced
with the drive letter (a or c) and the subdirectory to which you
copied the VClock files.

Now tab to the Icon field, and the VClock icon should appear.
If it does not, press the down-arrow key until you see the
VClock icon.

Press F10 (OK).

Now press the key-combination you want to use as the hot-key for
VClock (I use Alt+APPT; if you want to use something else, the
dialog which is displayed at this point shows you what your
options are).

---  Step 3: Start VClock  ---

Back at the Application Manager screen, highlight the VClock
icon and press Enter. To end VClock, press MENU, Q.


---                ---
---  Using VClock  ---
---                ---

To start VClock once it has been installed, hold down the ALT
key and press the APPT key (or whatever key you made the hot-key 
during the installation process). To quit VClock, press MENU, 
[Q]uit. VClock uses the same basic user interface as the built
in applications, so you should find operation of VClock to be
straight-forward. The documentation which follows explains the 
operations and features unique to VClock. 

---  Function Selection  ---

VClock can function in three modes: as a clock, displaying the 
current time of day (and, if the smallest character size is
selected, the date); stopwatch mode, in which an incrementing
timer is displayed; and timer mode, in which a decrementing 
timer is displayed. To select a mode, you can use the "Display"
menu, or you can use the [F9] and [F10] keys. [F9] and [F10] are
always set to the two modes not currently active. 

---  Clock Mode  ---

In clock mode, VClock shows a continuously updated time of day.
If the smallest character size is selected, the current date
will also be displayed. In clock mode [F6] through [F8] can be
used to control the chime selection. The current chime selection
is shown in the status area.

---  Stopwatch Mode  ---

In stopwatch mode, VClock shows an incrementing time display.
The stopwatch function is started and stopped using the [F5]
key or the spacebar. The value in the stopwatch can be reset
to zero using the [F7] key. The reset function zeros the
stopwatch regardless of whether it is running or stopped.

When the largest character size is used, the display will show
minutes and seconds for any value less than 1 hour; for values
of one hour or greater, only hours and minutes are displayed.

The stopwatch has a range of 24 hours. After 23 hours, 59 
minutes and 59 seconds have elapsed, the time value is reset to
zero, and the stopwatch continues to run.

---  Timer Mode  ---

In timer mode, the computer shows a decrementing time display.
The timer function can be started and stopped by pressing [F5]
or the spacebar. To set a value to count down from, press [F7]
to set an interval (such as 2 hours), or [F8] to set a target
time (such as 7:30). [F7] and [F8] cause a "Set Timer" dialog
to be displayed. The "Set Timer Interval" dialog allows you to
set a specific interval of time to count down from. The default
value is the current value of the timer. You can specify any
interval from 1 second to 23 hours 59 minutes and 59 seconds.
The timer status (running or stopped) remains unchanged by the
"Set Timer Interval" dialog.
 
When you set a timer interval, you have three options for what
action VClock will take when the timer reaches zero: it can
simply stop, and remain at zero; it can start the stopwatch
function, starting at zero; or it can restart the timer, using
the originally specified interval. You can also indicate whether
you want VClock to sound a beep when the interval has expired.

The "Set Timer Target" dialog allows you to set a specific time
of day at which the timer should reach zero. The default value
is the time-of-day at which the timer would reach zero if it
were currently running. If the current value is 0 hours and 0
minutes, then the default target will be the current time of
day.
 
When you set the timer using the "Set Timer Target" dialog, the
timer is automatically started when you press OK. When the timer
expires, a beep is sounded if the "Beep at zero" option was
selected, the timer is stopped, and the mode is set to clock.
The "Set Timer" dialogs can be entered regardless of whether the
timer is running or stopped. If you press [F9] to cancel the
dialog, then the current timer setting and state remain un-
changed.

If VClock is not the active application when the timer expires,
it momentarily becomes the active application. If the computer
is off when the timer expires, it is turned on.

---  Format of Time Displays  ---

The format of time and date displays is controlled by the built
in SETUP application. VClock always uses the same format as the
rest of the system (unless, as described below, "Force Seconds"
is selected). The prevailing system time format is used in all
of VClocks time displays, and is also the format expected when
entering time values in the "Set Timer" dialogs.

If the system time format includes seconds, then seconds will be 
included in the time-of-day displays (except when using the
largest character size). If you do not want to set your system
time format to include seconds, but want seconds to be displayed
in the VClock time-of-day display, you can use the "Force
seconds" option of the "Display" menu.

---  Seconds Display  ---

For clock displays, seconds can be displayed when the medium or
small character size is selected. If the currently selected
time format does not include seconds, display of seconds can be
forced by selecting the "Force seconds" selection of the
"Display" menu.
 
Note that for the clock function, seconds are never displayed
when the largest character size is selected, even if "Force
seconds" is selected. Seconds can only be displayed in the
medium or small character sizes.

In the largest character size, seconds are never displayed for
the clock function; however, for the stopwatch and timer
functions, if the time interval displayed is less than one hour,
then the display will automatically switch to show only the
minutes and seconds. The "Force Seconds" option has no effect on
timer or stopwatch displays.

---  Character Size  ---

VClock can display characters in three sizes. You switch between
the three sizes by pressing [Fn]+[spacebar] (this combination is
labeled "ZOOM" on the keyboard). The Zoom function cycles 
between the three sizes, just like it does in the built-in 
applications, such as Memo, except that the characters are much 
larger.

When using the largest character size, only a few characters can
be displayed. When the clock function is active, only hours and
minutes are displayed. When the stopwatch or timer function is
active, either hours and minutes, or minutes and seconds are
displayed, depending on whether the time is less than one hour.
If the time is less than one hour, then only minutes and seconds
are displayed. The next smaller size, medium, allows display of
hours, minutes and seconds. In clock mode, seconds will only be
displayed in this size if the currently selected time format
specifies seconds, or if the "Force seconds" option is selected.
The smallest size allows two lines to be displayed, and when in
clock mode the date is shown in addition to the time of day.

---  Chimes Control  ---

VClock has a chime function, which causes your computer to beep
at hourly or quarter-hourly intervals. You can control the
chimes with the Chime menu, or with [F6], [F7] and [F8] when the
clock function is active. If you select Quarter-hourly chimes, a
chime is sounded on the hour and at 15, 30, and 45 minutes past
the hour. If you select Hourly chimes, a chime is sounded on the
hour only. Pressing the [ESC] key will disable chimes, and will
also enable the normal timeout period.

The "Chime Time Control" dialog gives you greater control over
when chimes will be sounded by allowing you to specify whether
to allow a chimes for each 15-minute period in the day. This
dialog is activated by selecting the "Chime Time Control..."
item on the Chime menu. The Chime Control dialog is only used to
indicate when chimes are allowed - not to activate or deactivate
the chimes. Chimes must still be activated using [F7] or [F8]
(or the Chime Menu equivalents), or turned off entirely with 
[F6]. The default setting (when VClock is first installed) is to
allow chimes all day.

Finally, you can control the chime sound with the "Chime Sound" 
selection of the "Chime" menu. You can independently control
the sound and volume level of the hourly and the quarter-hourly
chimes. You can choose from four different built-in chime
sounds, or define your own customized chime sounds. (To define
your own custom chime sounds, see the accompanying vclock.cfg
file.) The setting for hourly chimes controls the sound and
volume for chimes sounded on the hour; that for quarter-hourly
chimes controls the chimes sounded at 15, 30, and 45 minutes
past the hour. (Chimes actually sound 1 second before the
designated times, to avoid conflicts with alarms sounded by the
appointment book application, and the "alarm clock" alarm in the
stopwatch application.)

Chimes are only sounded when VClock is open, though it need not
be the "active" (i.e. visible) application. If you close VClock,
then chimes will no longer be sounded, until you start VClock
once again.

---  System Timeout  ---

Under normal conditions, the computer will turn off after 3
minutes of no keypresses. (If the battery is low, this timeout
period is reduced to 1 minute.) Since you may want to watch the
time without otherwise using your computer, VClock provides a
way to extend the timeout period. VClock will not disable the
automatic timeout, but only extend it, to reduce the possibility
of accidentally discharging your batteries. The extended timeout
periods can be selected from the Timeout menu, or by using [F3]
or [F4].

You can set the timeout to 30 minutes or to 60 minutes. When you
extend the system timeout to one of these periods, the computer
will wait for the new, longer period before "timing out" and
turning itself off. You can postpone the time when the computer
turns off by pressing any key - the spacebar, for example. The 
"timeout" interval is restarted any time a key is pressed.

When the timeout period is set to "normal", by selecting the
"Normal" item from the "Timeout" menu, or by pressing [F2], the
system timeout period which was in effect when VClock was
started is restored. Normally, this is 3 minutes, but if you 
have set the timeout period to a different value by using a
utility program, then the timeout period set by that utility
will be restored. You can also restore the "normal" timeout
period by pressing the [ESC] key, but note that this also turns
off the chimes.

The extended system timeout value is observed only when VClock
is the active application. When you switch to another applica-
tion the system timeout value is reset to "normal" until you
return to VClock. The "normal" timeout setting is also restored
when you quit VClock. When the batteries become low, then the
timeout period is set to 1 minute. This "low battery" timeout
setting overrides any other timeout setting. If you request an
extended timeout period when the batteries are low, the request
is ignored. When the AC charger is plugged in the system never
turns off, and the timeout period has no meaning.

---  Status Area  ---

The status display area at the top of the screen, just below the
title bar, always shows the currently active function -- clock,
stopwatch, or timer -- and the current timeout period. For the
clock function, it also indicates whether chimes are off, or set
for hourly or quarter-hourly operation. For the stopwatch and
timer functions, there is an indication of whether the stopwatch
or timer is currently stopped or running.


---                    ---
---  Additional Notes  ---
---                    ---

--- Defining Yur Own Chimes ---

You can define your own chime sounds in the vclock.cfg
configuration file which is located on the C: drive in the
_DAT subdirectory. Use the MEMO application (or any text
editor) to edit this file. A sample vclock.cfg file is included
in this archive.

* Any line beginning with a semicolon ";" is a comment and is
  ignored by VClock.

* The section which defines chime sounds begins with a line
  consisting of "[Chimes]" (letter case is important).

* The actual chime sounds are defined by the following
  keywords, which may appear in any order (again, letter case
  is important).

  Keyword    Defines...
  =======    ==========
  Hours=     Chimes to be sounded on the hour
  Quarter1=  Chimes to be sounded at 15 minutes past the hour
  Quarter2=  Chimes to be sounded at 30 minutes past the hour
  Quarter3=  Chimes to be sounded at 45 minutes past the hour
  Quarter=   Chimes to be sounded at any quarter-hour not
             otherwise defined by a QuarterN= statement

* Following these keywords is a string of characters representing
  the chime sound. The characters and their meaning is the same
  as those used to define custom alarms for the built-in APPT
  application. They are described in the HP-200LX manual in the
  table "Commands for Custom Alarm Programming."

* These strings can be continued to the following line by using
  the "\" character as the last character on the line to be
  continued.

* The total size of all the chime strings combined cannot exceed
  1024 characters.


---  VClock and Alarms  ---

Any program which makes use of the alarm system on the HP 200LX
must in some way interact with the alarms used by the other
built-in applications. The chime and timer functions of VClock
make use of the alarm system so that chimes and timer alarms can
be sounded when VClock is not the active application.

Because of the regularity and frequency of chimes, there is a
side effect to using them: if you have chimes activated, it is
possible that you may miss notifications of past-due alarms.
Here is what happens: when an appointment book alarm comes due:
the system puts an alarm dialog box in the foreground and beeps;
then it waits for the alarm dialog to be acknowledged. Normally,
the alarm dialog box stays open until it is acknowledged, and
you are thus made aware of the past-due alarm. However, if
another alarm comes due before the first alarm is acknowledged,
the system closes the previous alarm dialog, unacknowledged, in
order to give control to the application owning the second
alarm. In the case of chimes, VClock is given control and it 
sounds the chime.

Because the appointment alarm was not acknowledged, but the 
system had to close the alarm dialog box to process the new
event, the alarm is simply marked "past due." You will not be
notified of this "past due" alarm until another appointment
book alarm comes due. Once you have acknowledged the new alarm,
appointment book then shows you any "past due" alarms.

This effect occurs with all types of alarms; however, you may
notice this more frequently if you use chimes, especially
quarter-hourly chimes, because they occur so frequently.

--- Chimes and Timeout  ---

In general, it is not a good idea to set an extended timeout
while chimes are active. This is because if you have a chime
period that is shorter than the timeout period, the computer
will never turn off -- every time a chime is sounded, that is
considered "activity", and the system timeout counter is
restarted -- and you could quickly run down the batteries.

---  Sleep Status  ---

If a timer alarm or a chime is activated while VClock is not the
active application, VClock momentarily becomes the active
application in order to process the alarm or chime. It then
relinquishes control to the application that had previously been
active. After that, the status of VClock is "Asleep." If you
close all other applications, you will see the topcard -- you 
will not be returned to VClock. Despite this, VClock is not 
closed, but merely "asleep", as you can see if you open the 
Application Manager, and set it to "list" mode. The difference 
between "Open" and "Asleep" is just that you will only be
returned to VClock if you explicitly start it by pressing the 
"hot-key" assigned to VClock, or by using Application Manager.
In other respects it still behaves as if it were "Open."


===============================================================
==========   VClock  -  Visible Clock  -  Version 2   =========
===============================================================
