<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>