THE RISC OS HOURGLASS

David Spencer looks at a useful feature provided by RISC OS.

The RISC OS Hourglass module is a short module that can be used to pop-up an egg timer on the screen as a mouse pointer. Its main use is to inform the user that the machine is tied up at the present time, and will not respond to keyboard input. The hourglass often appears when a directory is first opened using the Desktop.

Controlling the hourglass is simplicity itself. All controls are in the form of SWI commands, which are issued from Basic using the SYS statement. The two most important commands are:
SYS "Hourglass_On" and
SYS "Hourglass_Off"
As their names suggest, these are used to turn the hourglass on and off. The first command should be placed before any piece of code that takes a relatively long time to execute, and the second command afterwards, for example:
10 SYS "Hourglass_On"
20 PRINT "Start"
30 TIME=0
40 REPEAT UNTIL TIME>1000
50 PRINT "End"
60 SYS "Hourglass_Off"

This turns the hourglass on, prints 'Start', waits ten seconds, prints 'End' and finally turns the hourglass off. Incidentally, using the hourglass corrupts the definitions of pointers 3 and 4, although this will not normally be a problem.

If you try the above program, you might notice a small delay between the 'Start' being printed, and the hourglass appearing. This isn't at all accidental - instead, when you turn the hourglass on, it doesn't actually appear for 1/3 second, although the SYS command returns to the program immediately. This is so that the hourglass is only displayed if the operation takes a noticeable time (more than 1/3 second). Otherwise, the hourglass is turned off before it is displayed, and never actually appears. If the delay of 1/3 second is too long or too short, an alternative command can be used:
SYS "Hourglass_Start",delay
This is the same as 'Hourglass_On", but instead of using the fixed delay, the delay is specified as a parameter (in 100ths of a second). To illustrate this, change line 10 of the above program to:
10 SYS "Hourglass_Start",200

Hourglass on and off calls are nested. This means that if you turn the hourglass on more than once (without turning it off), you must turn it off the corresponding number of times before it is no-longer displayed. This ensures that in the situation where one routine that uses the hourglass calls another which also uses it, the hourglass is displayed until the first routine has finished, and isn't accidentally turned off by the second. The command:
SYS "Hourglass_Smash"
can be used to remove the hourglass display immediately, regardless of how many times it was turned on. This is very useful in error handling routines.

INDICATORS

As well as the basic hourglass, it is also possible to display a percentage figure below the 'egg timer', and two LED displays (blue bars) , one above and one below. For example, if the hourglass was displayed while a word processor reformatted a document, it might be helpful to display the percentage of the text that has been processed. The call to do this is:
SYS "Hourglass_Percentage",percent
If the value of percent is in the range 0 to 99, then the percentage is displayed. Any other value turns off the percentage display. To continually update the percentage, your program must issue this call each time the value changes.

The LEDs are controlled using:
SYS "Hourglass_LEDs",eor,and
The current state of the LEDs is represented by a two-bit number, bit 0 is set if the top LED is on, and bit 1 if the bottom LED is on. This call takes the current state, ANDs it with the parameter and, and Exclusive ORs the result with the parameter eor to get the new state. This allows you to achieve effects such as inverting the state of an LED, or changing one while leaving the other alone. The simplest way to use this command is to ignore the and parameter, and use the first parameter (eor) to specify the state of the LEDs. For example:
SYS "Hourglass_LEDs",2
will turn the bottom LED on, and the top one off.