<doc>
  <legacy_id>1513</legacy_id>
  <name>idle</name>
  <type>message</type>
  <syntax>
    <example>idle</example>
  </syntax>
  <library></library>
  <objects>
    <card/>
  </objects>
  <synonyms>
  </synonyms>
  <classification>
    <category>User Interaction</category>
  </classification>
  <references>
    <command tag="wait">wait Command</command>
    <command tag="revVideoGrabIdle">revVideoGrabIdle Command</command>
    <property tag="idleRate">idleRate Property</property>
    <property tag="idleTicks">idleTicks Property</property>
  </references>
  <history>
    <introduced version="1.0">Added.</introduced>
  </history>
  <platforms>
    <mac/>
    <windows/>
    <linux/>
    <ios/>
    <android/>
  </platforms>
  <classes>
    <desktop/>
    <server/>
    <web/>
    <mobile/>
  </classes>
  <security>
  </security>
  <summary>Sent periodically to the <glossary tag="current card">current card</glossary> if no other <keyword tag="message box">message</keyword> is being sent.</summary>
  <examples>
  </examples>
  <description>
    <p>Handle the <b>idle</b> <keyword tag="message box">message</keyword> to check constantly on the status of an <glossary tag="object">object</glossary>, the content of a <glossary tag="variable">variable</glossary>, and so forth, or to do periodic tasks.</p><p/><p><b>Comments:</b></p><p>The period between <b>idle</b> <glossary tag="message">messages</glossary> is specified by the <property tag="idleRate">idleRate</property> and <property tag="idleTicks">idleTicks</property> <property tag="properties">properties</property>.</p><p/><p><code/><b>Note:</b><code/> Usually, it is easier and more efficient to use the<code> send in <i>time</i> </code>form of the <b>send</b> <glossary tag="command">command</glossary> than to use an <b>idle</b> <glossary tag="handler">handler</glossary>, especially if a task needs to be <glossary tag="execute">executed</glossary> at regular intervals. This example shows an <b>idle</b> <glossary tag="handler">handler</glossary> that updates a clock timer:</p><p/><p><code>  on idle </code><code><i>-- avoid if possible</i></code></p><p><code>    global startTime</code></p><p><code>    if the seconds &gt; startTime + 60 </code><code><i>-- 60 seconds have gone by</i></code></p><p><code>      put the time into field "Clock Face"</code></p><p><code>      put the seconds into startTime</code></p><p><code>    end if</code></p><p><code>    pass idle</code></p><p><code>  end idle</code></p><p/><p>The following example does the same thing more efficiently, since it only needs to handle a single message every sixty seconds:</p><p/><p><code>  on updateClock </code><code><i>-- a better way</i></code></p><p><code>    put the time into field "Clock Face"</code></p><p><code>    send "updateClock" to me in 60 seconds</code></p><p><code>  end updateClock</code></p><p/><p>Executing an <b>idle</b> <glossary tag="handler">handler</glossary> slows down other LiveCode actions, so <glossary tag="handle">handle</glossary> the <b>idle</b> <keyword tag="message box">message</keyword> only in the rare cases where the <command tag="send">send</command> <glossary tag="command">command</glossary> cannot be used instead.</p><p/><p><code/><b>Note:</b><code/> If there is no <b>idle</b> <glossary tag="handler">handler</glossary> anywhere in the <glossary tag="message path">message path</glossary>, no <b>idle</b> <keyword tag="message box">message</keyword> is sent.</p>
  </description>
</doc>