SetTimeout

Name

SetTimeout -- install a new timeout function (V2.0)

Synopsis

[id] = SetTimeout(id, func, timeout[, userdata])

Function

This function installs a new timeout function and assigns the identifier id to it. If you pass Nil in id, SetTimeout() will automatically choose an identifier and return it. You need to specify a Hollywood function in the func argument and a timeout in milliseconds. After this time has elapsed, Hollywood will call your timeout function. This is useful if you need exact timing, for example if you want to synchronize graphics with music. Timeout functions are perfect for that.

You always need to use WaitEvent() in connection with this function! If you have a timeout function installed, the internal Hollywood timer scheduler will trigger timeout events and inform WaitEvent() to call your timeout function. Timeouts do not work without WaitEvent()! If you do not use WaitEvent(), your timeout function will never be called. Timeout functions are only called as long as you are in a WaitEvent() loop.

You can install as many timeouts as you want. Hollywood's internal scheduler will make sure that all timeout functions are called correctly.

You can use the ClearTimeout() call to stop a timeout function.

Starting with Hollywood 3.1 there is an optional argument called userdata. The value you specify here is passed to your callback function whenever it is called. This is useful if you want to avoid working with global variables. Using the userdata argument you can easily pass data to your callback function. You can specify a value of any type in userdata. Numbers, strings, tables, and even functions can be passed as user data.

Your timeout function will be called by Hollywood with one parameter. The parameter is a message table which contains the following fields:

Action:: Will be always set to Timeout. This field is a string!
ID:: Will be set to the identifier of the timeout that Hollywood has just called.
UserData:: Will be set to what you have specified in the userdata argument when you installed the timeout.

This message is useful if you want to handle two or more timeouts in the same function. The message tells you then which timeout Hollywood executed. If you do not need this message, simply disregard it.

Inputs

id: identifier for the new timeout function or Nil for auto id selection; the identifier is needed so that you can stop the timeout later using the ClearTimeout() command
func: Hollywood function to be called after the specified time has elapsed
timeout: time in milliseconds that specifies the timeout
userdata: optional: user specific data to pass to callback function (V3.1)

Results

id: optional: identifier of the timeout; will only be returned when you pass Nil as argument 1 (see above)

Example

Function p_TenSeconds()
  SystemRequest("Hollywood", "Ten seconds are over now!", "OK")
EndFunction

SystemRequest("Hollywood", "I will call the function TenSeconds()\n" ..
   "after 10 seconds have elapsed!\nCheck your watch, then click Go!",
   "Let's go!")

SetTimeout(1, p_TenSeconds, 10000)

Repeat
  WaitEvent
Forever

The code above installs a timeout function that will be called after 10000 milliseconds (= 10 seconds) have elapsed.

Show TOC