Window.setTimeout() (Method)

A timeout control method.

Availability:

JavaScript - 1.0
JScript - 1.0
Internet Explorer - 3.02
Netscape - 2.0
Opera - 3.0
Property/method value type:Number primitive
JavaScript syntax:-myWindow.setTimeout(aFunction, aWaitTime)
-myWindow.setTimeout(aFunction, aWaitTime, someArguments)
-myWindow.setTimeout(aFunction, aWaitTime, someArguments, aLanguage)
-myWindow.setTimeout(aSourceText, aWaitTime)
-myWindow.setTimeout(aSourceText, aWaitTime, someArguments)
-myWindow.setTimeout(aSourceText, aWaitTime, someArguments, aLanguage)
-setTimeout(aFunction, aWaitTime)
-setTimeout(aFunction, aWaitTime, someArguments)
-setTimeout(aFunction, aWaitTime, someArguments, aLanguage)
-setTimeout(aSourceText, aWaitTime)
-setTimeout(aSourceText, aWaitTime, someArguments)
-setTimeout(aSourceText, aWaitTime, someArguments, aLanguage)
Argument list:aFunctionA function object
aLanguageA scripting language to execute the script source (MSIE only)
aWaitTimeA time interval in milliseconds
aSourceTextSome valid script source text
someArgumentsThe arguments to the function object (not supported in MSIE version 4)

The setTimeout() method provides a way to defer the execution of a fragment of script source text. It is analogous to the eval() method with a delay before execution. Although this method returns an ID value that can then be used with the clearTimeout() method to cancel the execution, it is very likely that the deferred code will have executed already. You should set a flag accordingly so that you can avoid killing a deferred task that has already been completed. Attempting to kill deferred tasks that are no longer pending can crash your browser.

Code executed by this deferred mechanism will only be executed once. If you want it to be executed continuously then setInterval() is a better alternative. On the other hand, you may want to conditionally defer it again in which case you should call a handler function and, before exiting it, make another call to setTimeout() to activate another deferred task.

As is the case with setInterval() and eval(), you can execute multiple statements as long as they are separated by semi-colons.

Passing a function as one of the arguments is supported by MSIE in version 5 upwards and by Netscape Navigator in version 4 upwards. The scripting language can only be defined in MSIE.

This facility may be used to present a message in the status bar and then clear it again after some period of time has elapsed. It can be used to generate some animation in the status bar, although many people consider this to be a design cliche and much overused. If you do animate the status bar, you should consider whether it is useful and not distracting.

These timed animations are generally best triggered by an onLoad event handler.

Note that the deferred code is executed in the context and scope chain of the window object that received the method call to set up the deferred task.

The example is a cut down version of the ticker script used in the BBC News Online web site. The display techniques are the same but the example only shows one story. To see the real ticker in operation, refer to http://www.bbc.co.uk/news and view it with an MSIE browser. In the News Online ticker, many coding compromises were necessary to work round object boundary bugs in the MSIE for Macintosh browser. Because the ticker is constantly being updated, the object boundary is changing all the time and although this was played in an <IFRAME>, the mouse enter and mouse out events caused the MSIE browser to crash frequently. Earlier versions of the ticker also did a large amount of string creation/destruction which caused somewhat massive memory leaks. You can alleviate this by using meta refresh tags to force the garbage collection to happen.

Warnings:

Example code:

   <HTML>
   <HEAD>
   <STYLE  TYPE="text/css">
   <!--
   A
   {
      font-family: Verdana, Arial, Helvetica, sans-serif, "MS sans serif";
      font-size: 11px;
      line-height: 11px;
      text-decoration: none;
      color: #333366;
      font-weight: bold;
   }
   
   A.latest
   {
      color: #CC3300;
   }
   
   A:hover
   {
      color: #CC3300;
   }
   -->
   </STYLE>
   <SCRIPT LANGUAGE=JAVASCRIPT>
   // This script will only work on MSIE
   var theTickerText       = "The ticker text goes here and plays out until it is finished before repeating again.";
   var theCharacterTimeout = 45;
   var theStoryTimeout     = 5000;
   var theEnumerator       = 0;
   // --- Run the ticker
   function doTheTicker()
   {
      if((theEnumerator % 2) == 1)
      {
         writeTicker("_");
      }
      else
      {
         writeTicker("*");
      }
   
      theEnumerator++;
   
      if(theEnumerator == theTickerText.length+1)
      {
         writeTicker("");
         theEnumerator = 0;
         setTimeout("doTheTicker()", theStoryTimeout);
      }
      else
      {
         setTimeout("doTheTicker()", theCharacterTimeout);
      }
   }
   
   function writeTicker(aWidget)
   {
      document.all.hottext.innerHTML = theTickerText.substring(0,theEnumerator) + aWidget;
   }
   </SCRIPT>
   </HEAD>
   <BODY onLoad="doTheTicker();">
   <A ID="latest" CLASS="latest" HREF="/" target=_top>LATEST: </A><A ID="hottext" HREF="/"></A>
   </BODY>
   </HTML>

See also:clearTimeout(), eval(), Frame object, Memory leak, Timeout handlers, Window object, Window.clearInterval(), Window.clearTimeout(), Window.setInterval()