Event Scheduler

From Frontal Wiki

Introduction

A scheduler is used to automatically run a script after some period of time, for some period of time and with some frequency.

Delaying a Function

The most common use of the scheduler is to delay the running of some function. In this example, we add a dark magenta div to the document when you click the text and then delete it 1 second later.

<style><![CDATA[
    #test
        {
            @onClick
            {
                var elemDefn = new XMLList ( "<div />" );
                document.insertXML ( elemDefn as XMLList );
                var elem = document.getNodeElement ( elemDefn );
                com.frontalcode.Scheduler.setTimeout ( function ( )
                    {
                        elem.destroy ( );
                    }, 1 );
            }
        }
    div
        {
            float: left;
            margin: 10px;
            width: 20px;
            height: 20px;
            background-color: darkmagenta;
        }
]]></style>
<text id="test">click me!</text>

The 1 second delay in the example is caused by the call to com.frontalcode.Scheduler.setTimeout. This static method of the Scheduler task returns a task id and takes these parameters:

• functionReference: The function to call at the end of the time out.
• delay: How long to delay in seconds before running the function.
• useFrameClock: If true (the default), then the delay will be based on the passage of frames rather than the wall clock. That is, if the delay is two seconds and the movie's frames-per-second is 30, then the delay is actually for 60 frames.
• ...: Any number of additional parameters may be given. These will be passed to the function at the end of the time out.

There is a similar function to delay a function based on a number of frames. This is com.frontalcode.Scheduler.setTimeoutInFrames. It returns a task id and takes these parameters:

• functionReference: The function to call at the end of the time out.
• delay: How long to delay in frames before running the function.
• ...: Any number of additional parameters may be given. These will be passed to the function at the end of the time out.

Scheduling a Task

Delaying a function is a special case of scheduling a task. By scheduling task, we can delay it but then also have it run periodically and for some period of time.

For example, here we wait 3 seconds and then count each second from 1 to 5.

<script><![CDATA[
var x = 1;
var taskId = com.frontalcode.Scheduler.gI().scheduleTask ( null, function ( )
    {
        document.write ( x++ );
    }, null, 3, 4, 1 );
]]></script>

The scheduleTask method of the Scheduler singleton (com.frontalcode.Scheduler.gI()) returns a task id and takes these parameters:

• taskId: If null or zero then a new task is created. Otherwise, if the id is that of an existent task, then the call is ignored.
• function: Either a function reference or a method name as a string. This is what will be run when the task is due.
• parameters: An array of parameters to pass to the scheduled function.
• delay: How long to delay (in seconds) before starting the task. The default is 0.
• endAfterSecs: How many seconds the task will scheduled for. Set to null (the default) to run forever.
• everyXSecs: How often to run the task during the time after delay and until endafterSecs. The default is null which means the task will run every frame.
• object: If non-null, the function will be applied to this object thus treating it like a method of the object. If function is a string then it is on this object that the method is sought.
• runNow: Normally the scheduled task will delay a frame before it is run even if the delay is 0. This is because the Scheduler checks its tasks once per frame. If runNow is set to true though then the Scheduler will immediately check if the task should be run. The default is false.
• useFrameClock: If true (the default), then the times will be based on the passage of frames rather than the wall clock. That is, if the delay is two seconds for example and the movie's frames-per-second is 30, then the delay is actually for 60 frames. The default is true.
• doNotPrependStatusArguments: The function is normally called with only the parameters specified. If this is false though then three parameters will be inserted before these parameters. The default is true. The parameters are:
  • taskId: The id of the task being run.
  • runningForSecs: How long the task has been running for since its delay passed. (The time is in seconds though skewed if useFrameClock is true.)
  • endInSecs: How much longer the task has to run or null if it is running indefinitely.
• useFrames: If true then all the times are in frames instead of seconds.

Managing Tasks

There are several functions that may be used to manage tasks. Each are method of the Scheduler singleton instance accessed with "com.frontalcode.Scheduler.gI()".

• getTask will find a task by its id. It returns an Object that defines the task and takes a single parameter:
  • taskId: the id of the task to find.

• resetTask will make a task behave as if it were just scheduled. It preserves all of its original arguments. The method takes a single parameter:
  • taskId: the id of the task to reset.

• pauseTask will pause a task. A paused task will have all of its timers frozen and so its delay will not pass, nor its end time approach while paused. The method returns true if the task were running and false if it were already paused. It takes a single parameter:
  • taskId: the id of the task to pause.

• resumeTask will resume a paused task. The method returns true if the task were paused and false if it were already running. It takes a single parameter:
  • taskId: the id of the task to resume.

• removeTask will remove a task. It takes a single parameter:
  • taskId: the id of the task to remove.

• enableScheduler may be used to enable or disable the scheduler. It takes a single parameter:
  • value: Pass true to enable the scheduler otherwise false.