; > &.Doc.Hourglass
;

The Hourglass module will change the pointer shape to that of an Hourglass.
You can optionally also display a percentage figure and two "LED" indicators
for status information.

The Hourglass interface is via the following SWI's

Hourglass_On
------------
Entry:
Exit:

This turns on the Hourglass. Although control return immediately there is a
delay of 1/3 of a second before the Hourglass becomes visible. Thus the client
can bracket an operation by Hourglass_On/Hourglass_Off and the hourglass
will only be displayed if the operation takes longer than 1/3 of a second.
(For delays other than the default see Hourglass_Start).

Hourglass_On's are nestable. If the Hourglass is already visible then a count
is incremented and the Hourglass will remain visible until an equivalent
number of Hourglass_Off's are done.

Hourglass_Off
-------------
Entry:
Exit:

This will turn off the Hourglass, unless of course there are nested 
Hourglass_On calls in which case the Hourglass stays visible until
an equal number of Hourglass_Off calls are made.

When the Hourglass is removed the pointer number and colours are restored
to those in use at the first Hourglass_On.

Note that cursor shapes 3 and 4 are used (ie corrupted!) by the Hourglass,
but users should not have been using these anyway.

Hourglass_Smash
---------------
Entry:
Exit:

Will turn off the Hourglass immediately taking no notice of nested 
Hourglass_On's. A last ditch call for when you are sure neither you,
nor anyone else, should be displaying an Hourglass.

Hourglass_Start
---------------
Entry:
    R0 = Delay before startup in centi-seconds.
Exit:

Similar to Hourglass_On, except you can provide your own startup delay.

A delay of zero can be used to suppress the Hourglass, so future
Hourglass_On and Hourglass_Start calls have no effect. This only applies
if the Hourglass is currently off. The condition is terminated by the
matching Hourglass_Off, or by an Hourglass_Smash.


Hourglass_Percentage
--------------------
Entry:
    R0 = (0-99) Percentage to display
         otherwise turn off Percentage
Exit:

The user can display a Percentage below the Hourglass. If in the
range 0-99 it is displayed, values outside this range turn off the
percentage. 

The initial condition of an Hourglass is to have Percentages turned off.

Hourglass_LEDs
--------------
Entry:
    R0, R1 setup LEDs  
            NewLEDs = (OldLEDs AND R1) XOR R0
Exit:
    R0 = OldLEDs

The are two display indicators above the Hourglass which can be used
to display status information. These correspond to bits 0,1 of the
LEDs word. Bit set indicates indicator on.

The default condition is all indicators off.