chiark - git - mdw - ssr/blob - StraySrc/Libraries/Sapphire/sh/hour

   1 ;
   2 ; hour.sh
   3 ;
   4 ; Handling of the hourglass
   5 ;
   6 ; © 1994-1998 Straylight
   7 ;
   8
   9 ;----- Licensing note -------------------------------------------------------
  10 ;
  11 ; This file is part of Straylight's Sapphire library.
  12 ;
  13 ; Sapphire is free software; you can redistribute it and/or modify
  14 ; it under the terms of the GNU General Public License as published by
  15 ; the Free Software Foundation; either version 2, or (at your option)
  16 ; any later version.
  17 ;
  18 ; Sapphire is distributed in the hope that it will be useful,
  19 ; but WITHOUT ANY WARRANTY; without even the implied warranty of
  20 ; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21 ; GNU General Public License for more details.
  22 ;
  23 ; You should have received a copy of the GNU General Public License
  24 ; along with Sapphire.  If not, write to the Free Software Foundation,
  25 ; 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  26
  27 ;----- Overview -------------------------------------------------------------
  28 ;
  29 ; Functions provided:
  30 ;
  31 ;  hour_init
  32 ;  hour_on
  33 ;  hour_off
  34 ;  hour_percent
  35 ;  hour_leds
  36 ;  hour_suspend
  37 ;  hour_save
  38 ;  hour_resume
  39 ;  hour_restore
  40
  41                 [       :LNOT::DEF:hour__dfn
  42                 GBLL    hour__dfn
  43
  44 ; --- hour_init ---
  45 ;
  46 ; On entry:     --
  47 ;
  48 ; On exit:      --
  49 ;
  50 ; Use:          Initialises the hour system, so it will display an hourglass
  51 ;               when necessary.
  52 ;
  53 ;               Since this gets called at a random point during the Sapphire
  54 ;               initialisation, and we can rely on Hourglass keeping its
  55 ;               own count, the suggested way of handling everything properly
  56 ;               is as follows:
  57 ;
  58 ;                               SWI     Hourglass_On
  59 ;                               BL      sapphire_init
  60 ;                               SWI     Hourglass_Off
  61
  62                 IMPORT  hour_init
  63
  64 ; --- hour_on ---
  65 ;
  66 ; On entry:     --
  67 ;
  68 ; On exit:      --
  69 ;
  70 ; Use:          Turns the Hourglass on only if it isn't on already.
  71 ;               Otherwise its status is left as it was.
  72
  73                 IMPORT  hour_on
  74
  75 ; --- hour_off ---
  76 ;
  77 ; On entry:     --
  78 ;
  79 ; On exit:      --
  80 ;
  81 ; Use:          Turns the Hourglass off if it's only been turned on once.
  82 ;               If the Hourglass gets turned off, all the information about
  83 ;               it (percentage and LEDs) get forgotten.
  84
  85                 IMPORT  hour_off
  86
  87 ; --- hour_percent ---
  88 ;
  89 ; On entry:     R0 == percentage value to display, or -1 to remove
  90 ;
  91 ; On exit:      --
  92 ;
  93 ; Use:          Attaches a percentage display to the Hourglass.
  94
  95                 IMPORT  hour_percent
  96
  97 ; --- hour_leds ---
  98 ;
  99 ; On entry:     R0 == LED mask EOR value
 100 ;               R1 == LED mask AND value
 101 ;
 102 ; On exit:      --
 103 ;
 104 ; Use:          Changes the Hourglass LED status.
 105
 106                 IMPORT  hour_leds
 107
 108 ; --- hour_suspend ---
 109 ;
 110 ; On entry:     R0 == pointer to 2 word block to save status in
 111 ;
 112 ; On exit:      --
 113 ;
 114 ; Use:          Saves the Hourglass state in a block you've pointed at,
 115 ;               and disables the Hourglass.  Useful if you want to do some
 116 ;               user interaction without polling (e.g. an error box).
 117
 118                 IMPORT  hour_suspend
 119
 120 ; --- hour_save ---
 121 ;
 122 ; On entry:     R0 == pointer to 2 word block to save status in
 123 ;
 124 ; On exit:      --
 125 ;
 126 ; Use:          Saves the current Hourglass status without altering it.
 127
 128                 IMPORT  hour_save
 129
 130 ; --- hour_resume, hour_restore ---
 131 ;
 132 ; On entry:     R0 == pointer to 2 words filled by hour_suspend or hour_save
 133 ;
 134 ; On exit:      --
 135 ;
 136 ; Use:          Restores the Hourglass state to that saved away by one
 137 ;               of the previous two calls.  This routine has two names.
 138
 139                 IMPORT  hour_resume
 140
 141 ; --- hour_resume, hour_restore ---
 142 ;
 143 ; On entry:     R0 == pointer to 2 words filled by hour_suspend or hour_save
 144 ;
 145 ; On exit:      --
 146 ;
 147 ; Use:          Restores the Hourglass state to that saved away by one
 148 ;               of the previous two calls.  This routine has two names.
 149
 150                 IMPORT  hour_resume
 151                 IMPORT  hour_restore
 152
 153                 ]
 154
 155 ;----- That's all, folks ----------------------------------------------------
 156
 157                 END