Mac Home Automation

This verb takes it's name from the “idle” handler in a compiled applescript. It can be used to re-execute a global script very quickly or continually without having to clog up the schedule events window. Scheduled events only have a granularity of 1 second anyway, but if you wanted something to run faster than that you'd need to use this. This verb can be called from anywhere. This is considered an advanced scripting topic and you should use the “execute script” verb whenever possible as opposed to this.

start idler (text, name of a global script, Unit or Interface) handler (optional, name of a handler in the global script if not supplied the script will be run normally) in (optional, how long to wait in milliseconds before running the handler for the first time. Passing a value of 1000 would result in the first running of the hander in 1 second. After the first run the returned value from the script or handler will be used to schedule the next callback.)

start idler (ThisScript) handler “StepTwo” in 500

on StepTwo()
  write log “your idle timer is running!"
  return 5000
end StepTwo

would execute the handler “on stepTwo()” in half a second. The return of 5000 would keep the callback happening every 5 seconds after that. You must return a value other than 0 to keep the idler running. If there is an unhandled error in the handler or if the handler returns 0 the idle callback will be stopped. You can change the timing of the next callback for whatever reason by returning a different number of milliseconds.

Note that this is not a perfect timer. When the callback will actually happen will be no sooner than the number of milliseconds that you request, but will be some small random amount more than that due to system and program load at the time that it expires.

The minimum value for a callback is 10ms but you definitely do not want to do that repeatedly for very long as you could definitely start to lag the program. While XTension will not let you set a callback in less than 10 milliseconds, there is little chance it will actually happen quite that quickly.

You can also execute handlers in unit ON scripts or in Interface scripts (like the DIY interface) with this verb. While the name parameter is optional if you’re starting a handler in a script because it can use the global (thisScript) value you must include the unit or interface name in order to have the idle timer be called back into either of those types of scripts.

• Upon the call to start idler the global script will execute. It must then return a number of milliseconds before it will be run again. If 0 is returned the script will stop being called.
• Setting a small number here or doing a lot of work inside a rapidly executing script could bring other performance to a halt.
• a script can only have one idler timer, so it doesn't hurt to call start idler more than once. It will cause the script to run again upon the call, but will not leave 2 timers active for the script.
• I use this to update remote display clock displays via the DIY interface and returning “1000” to make the script run and update the clock every second. Since no script executed log lines are shown when the timer re-runs the script the log is not spammed with an entry even second like it would be if I were doing this via the execute script “clock” in 1 command.
• to stop the idler the script must return 0 or use the Stop Idler verb.
• you cannot pass parameters to the handler specified in the handler parameter, only it’s name.
• If you wish to switch to calling a different idler from within the idle handler you must return the time before you want it to change and not use the “in” property of the start idler command. If you don’t return a number of MS the idle timer is stopped even if you changed it to a different handler further up the script.

See Also: Stop Idler

version 9.1 added support to run an idler callback in a units ON script or an Interface script