Timeout Objects

May 15, 2001
by David Berger

It is often the case that you need to trigger events after a certain amount of time or at regular intervals. For example: you are streaming in a Shockwave movie and you want to check the mediaReady property of a certain member every 2 seconds to find out when it's ready for use. Once it is ready you do not need to check it again.

Traditionally this sort of programming involved variations of keeping track of elapsed time in global variables or object and behavior properties. Sometimes the timer was used. Often the scripts involved manipulating the actorList and relying on stepFrame messages. These techniques frequently lead to buggy and difficult-to-read code. With the introduction of timeout objects in Director 8 there is now a more elegant solution.

The basic idea is that you create a timeout object. You tell the timeout object what handler you want executed at given time intervals. The timeout object gets added to the timeoutList which is a system property containing a linear list of active timeout objects. Each timeout object in the timeoutList gets processed automatically until you explicitly remove it with the forget function. The new function is used to create timeout objects.

timeout ("thetimeOutName").new (1000, #theHandlerToCall, theTarget)

Each timeout object is identified by a string value used for the name. The name of the timeout object in the example above is "thetimeOutName".

The second parameter of the new function specifies which handler should get called when the timeout is triggered. This is stored in the timeoutHandler property of the object. Notice that you pass in the handler name as a symbol.

The first parameter specifies how often the timeoutHandler should get called. It is measured in milliseconds, so in the example, theHandlerToCall gets called every second. This is stored in the period property of the timeout object.

The third parameter specifies the location of the timeoutHandler. This is stored in the target property of the timeout object. If the target is blank, Director will look for the handler in a movie script. I prefer to set up timeout handlers and keep the handlers I want called within an instance of a parent script. In that case you pass me as the target.

Try executing the code in the message window.

timeout ("thetimeOutName").new (1000, #theHandlerToCall, theTarget)
put the timeoutlist
-- [timeOut("thetimeOutName")]

Here is the example movie.

Here is the code for the movie with comments.

on prepareMovie
--create the timeoutobject
timeout ("annoyTheUser").new (5000, #callAlert)
end

on callAlert
alert "Click the button."
end

on buttonClicked
--remove the timeoutoject from the timeoutlist when the button is clicked
timeout ("annoyTheUser").forget ()
end

timeout objects are especially useful for asynchronous operations such as many of the Net Lingo Calls. A typical call looks like:

gnetid = getnettext ("http://www.mysite.com/mytext.htm")

The timeout object can periodically check to determine if the operation is done. While this was often done in an exitFrame handler, you can now check with a timeout object. Add the timeout object after the call to getNetText and add a handler in a movie script to check for the operation when called .

timeout ("checkNetOperation").new (1000, #checktheNetOperation)

on checktheNetOperation
  if netdone (gnetid) then
    --if the operation is done kill the timeout object
    timeout ("checkNetOperation").forget ()
    if neterror (gnetid) = "OK" then
      res=netTextResult (gnetid)
      --do the rest of the processing
      process res
    end if
  end if
end

I also use timeout objects when I want two Shockwave movies to pass information to each other. The first movie adds a timeout object that calls a handler which polls for the existence of a preference file of a given name by calling the getPref function every few seconds. When the second movie needs to pass data, it writes to the preference file. As soon as the first movie gets data from the file, it can kill the timeout object using the forget function. Basically, timeout objects are so useful that if you are still using Director 7, you might want to upgrade just for this feature.

A sample Director 8 movie is available for download in Macintosh or Windows format.

David Berger is the Lead Programmer, founder, and owner of Scientia, a Web and multimedia development company in New York City. He has been using Director since it was VideoWorks and samples of this work can be found at http://www.scientia.org.