SoftTimer-module by Deniil 715!


What is it?
~~~~~~~~~~~
SoftTimer_oo.m contains a class that uses the timer.device for
delay of microseconds and/or seconds.


Usage of the class methods:
~~~~~~~~~~~~~~~~~~~~~~~~~~~
DEF st:PTR TO softtimer

-----------------
softtimer(pri=0,doNotRaise=FALSE) -> This is the constructor to the class.
^^^^^^^^^
Usage: NEW st.softtimer() -> will initiate the timer with default values.

'pri' can be 32, 16, 0, -16, -32, default is 0.
'doNotRaise' can be set nonzero if you don't want failures to be
             reported as raised exceptions but manually checked
             through 'st.err'
             Default is FALSE. Recommended to keep it that way!
-----------------

startTimer(secs,micro=0) -> This will start the timer with specified
^^^^^^^^^^                  time-values.

Usage: st.startTimer(5,300000) -> will wait 5.3 seconds.

'secs' is how many seconds you want the timer to run before it
       signals your task on sigbit 'st.sig'.
'micro' is how many microseconds you want the timer to run before
        it signals your task as with seconds.
        Default is 0 microsecs.
-----------------

stopTimer() -> will stop a running timer.
^^^^^^^^^
Usage: st.stopTimer()
-----------------

delay(secs,micro=0) -> will wait the specified time.
^^^^^
Usage: st.delay(120) -> will wait 2 minutes.

'secs' and 'micro' is the same as for startTimer().

-----------------

waitForTimer() -> will wait for the timer to finish and then return.
^^^^^^^^^^^^
Usage: st.waitForTimer()

NOTE: This call could be dangerous if you're unsure of the remaining
      time that the timer will run couse your task will be frozen
      until the timer has finished!
-----------------

waitForThings(signals=0) -> waits for the timer AND any other signal
^^^^^^^^^^^^^               that might arrive.
                            The function of this method is equal to
                            Wait(signals OR st.sig).

Usage: st.waitForTimer(Shl(1,win.userport.sigbit))
       This call will now wait for signals from the timer and
       the userport of the window 'win'.

'signals' is the same signal-mask that you pass can to Wait().

NOTE: Wait() is in my opinion to prefer as it is less code
      to write and it is faster than waitForThings().
-----------------

waitAndRestart(secs,micro=0) -> will wait until a running timer finishes
^^^^^^^^^^^^^^                  and then restart it as the startTimer()
                                does.
                                This method could be useful for demos,
                                games etc.

Usage: FOR x:=0 TO 100
        st.waitAndRestart(0,100000) -> wait 1/10 of a second
        -> doStuffThatShouldBeDoneTenTimesASecond()
       ENDFOR

'secs' and 'micro' is the same as for startTimer().
-----------------

getTimerMsg() -> is used to check if your timer has finished or not.
^^^^^^^^^^^
Usage: IF st.getTimerMsg()=TRUE
        WriteF('Timer counted to zero!\n')
       ELSE
        WriteF('Timer still running!\n')
       ENDIF
-----------------

end() -> destructor that will deallocate all messageports and stuff.
^^^
Usage: END st -> END will search the softtimer for an end()-method
                 and execute it as st.end().

NOTE: This could be used as just st.end() if you later want to reuse
      it without NEW, just st.softtimer(). Not recommended though!
-----------------


Errors?
~~~~~~~
Errors will normally be raised as exceptions. However, if you specify
doNotRaise=TRUE when you initiate the softtimer you have to check the
errors by yourself by compare the st.err against theese errors:

ERR_MSGPORT -> The message-port coouldn't be created. (CreateMsgPort())
ERR_TIMER   -> The timerequest couldn't be created.   (createStdIO())
ERR_DEV     -> The timer.device couldn't be opened.   (OpenDevice())

ERR_NONE    -> Everything went well and you're ready to use your timer.
               This will never be raised since it's not an error.

Remember that the NEW-keyword might raise itself if out of memory!!


Author?
~~~~~~~
Daniel Westerberg  alias  Deniil715!
E-mail: deniil@algonet.se  or  onyxsoft@alfaskop.net


Bugs?
~~~~~
Don't think so ;)
Report to author if you find anyone!  (please don't find any!!:)

It has been tested on:
A1200 Blizz1230/50 OS39 2+16 MB Ram DBLPal ..