<doc>
  <legacy_id>1196</legacy_id>
  <name>flushEvents</name>
  <type>function</type>
  <syntax>
    <example>flushEvents(<i>eventType</i>)</example>
  </syntax>
  <library></library>
  <objects>
  </objects>
  <synonyms>
  </synonyms>
  <classification>
    <category>User Interaction</category>
  </classification>
  <references>
    <command tag="cancel">cancel Command</command>
    <message tag="appleEvent">appleEvent Message</message>
    <message tag="suspendStack">suspendStack Message</message>
    <message tag="resumeStack">resumeStack Message</message>
  </references>
  <history>
    <introduced version="1.0">Added.</introduced>
  </history>
  <platforms>
    <mac/>
    <windows/>
    <linux/>
  </platforms>
  <classes>
    <desktop/>
    <server/>
  </classes>
  <security>
  </security>
  <summary>Clears pending <glossary tag="event">events</glossary> from the event queue so they will not <glossary tag="trigger">trigger</glossary> <glossary tag="handler">handlers</glossary>.</summary>
  <examples>
    <example>put flushEvents("activate") into trashVar</example>
    <example>get flushEvents("all")</example>
  </examples>
  <description>
    <p>Use the <b>flushEvents</b> <control_st tag="function">function</control_st> to prevent unwanted <glossary tag="message">messages</glossary> from being sent during a <glossary tag="handler">handler's</glossary> <glossary tag="execute">execution</glossary>.</p><p/><p><b>Parameters:</b></p><p>The <i>eventType</i> is one of the following:</p><p/><p><code>all</code>: ignore all waiting events</p><p><code>mouseDown</code>: ignore mouse presses</p><p><code>mouseUp</code>: ignore mouse releases</p><p><code>keyDown</code>: ignore keypresses</p><p><code>keyUp</code>: ignore key releases</p><p><code>autoKey</code>: ignore key repeats</p><p><code>disk</code>: ignore disk-related events</p><p><code>activate</code>: ignore windows being brought to the front</p><p><code>highLevel</code>: ignore Apple Events (on Mac OS and OS X systems)</p><p><code>system</code>: ignore operating system events</p><p/><p><b>Value:</b></p><p>The <b>flushEvents</b> <control_st tag="function">function</control_st> always <glossary tag="return">returns</glossary> empty.</p><p/><p><b>Comments:</b></p><p>Typically, you use the <b>flushEvents</b> <control_st tag="function">function</control_st> in a <glossary tag="handler">handler</glossary> to dump user actions that have occurred during the handler. For example, if a button has a <message tag="mouseUp">mouseUp</message> <glossary tag="handler">handler</glossary> that takes a few seconds to run, the user might click again during that time. To prevent those extra clicks from causing the <glossary tag="handler">handler</glossary> to run again, use the <b>flushEvents</b> <control_st tag="function">function</control_st>:</p><p/><p><code>  on mouseUp</code></p><p><code>    </code><code><i>-- ...lengthy handler goes here...</i></code></p><p><code>    </code><code><i>-- get rid of clicks since the handler started:</i></code></p><p><code>    put flushEvents("mouseUp") into temp</code></p><p><code>  end mouseUp</code></p><p/><p>To clear multiple event types, call the <b>flushEvents</b> <control_st tag="function">function</control_st> once for each event type you want to clear.</p><p/><p>Although some of the <i>eventTypes</i> have the same names as built-in <glossary tag="LiveCode">LiveCode</glossary> <glossary tag="message">messages</glossary>, there is a distinction. For example, the <code>mouseDown</code> <glossary tag="event">event</glossary> type is the operating system's response to the user clicking the <glossary tag="mouse button">mouse button</glossary>. When the operating system sends this <glossary tag="event">event</glossary> to the <glossary tag="application">application</glossary>, LiveCode sends a <message tag="mouseDown">mouseDown</message> <keyword tag="message box">message</keyword> to the target <glossary tag="object">object</glossary>. The expression<code> flushEvents(mouseDown) </code>prevents the application from responding to any <code>mouseDown</code> <glossary tag="event">events</glossary> it has received from the operating system, but has not yet processed.</p>
  </description>
</doc>