<doc>
  <legacy_id>2244</legacy_id>
  <name>pass</name>
  <type>control structure</type>
  <syntax>
    <example>pass <i>messageName</i> [to top]</example>
  </syntax>
  <library></library>
  <objects>
  </objects>
  <synonyms>
  </synonyms>
  <classification>
  </classification>
  <references>
    <command tag="call">call Command</command>
    <control_st tag="exit">exit Control Structure</control_st>
    <keyword tag="end">end Keyword</keyword>
    <property tag="backgroundBehavior">backgroundBehavior Property</property>
    <property tag="dynamicPaths">dynamicPaths Property</property>
  </references>
  <history>
    <introduced version="1.0">Added.</introduced>
    <changed version="2.1"></changed>
  </history>
  <platforms>
    <mac/>
    <windows/>
    <linux/>
    <ios/>
    <android/>
  </platforms>
  <classes>
    <desktop/>
    <server/>
    <web/>
    <mobile/>
  </classes>
  <security>
  </security>
  <summary>Stops the current <glossary tag="handler">handler</glossary> and <glossary tag="pass">passes</glossary> the <keyword tag="message box">message</keyword> to the next <glossary tag="object">object</glossary> in the <glossary tag="message path">message path</glossary>.</summary>
  <examples>
  </examples>
  <description>
    <p>Use the <b>pass</b> <glossary tag="control structure">control structure</glossary> to end a <glossary tag="handler">handler</glossary> while letting the <keyword tag="message box">message</keyword> continue along the <glossary tag="message path">message path</glossary>.</p><p/><p><b>Form:</b></p><p>The <b>pass</b> <glossary tag="statement">statement</glossary> appears on a line by itself, anywhere inside a <glossary tag="handler">handler</glossary>.</p><p/><p><b>Parameters:</b></p><p>The <i>messageName</i> is the name of the <glossary tag="handler">handler</glossary> in which the <b>pass</b> <glossary tag="control structure">control structure</glossary> appears.</p><p/><p><b>Comments:</b></p><p>When the <b>pass</b> <glossary tag="control structure">control structure</glossary> is <glossary tag="execute">executed</glossary>, any remaining <glossary tag="statement">statements</glossary> in the <glossary tag="handler">handler</glossary> are skipped. Hence, the <b>pass</b> <glossary tag="control structure">control structure</glossary> is usually used either at the end of a <glossary tag="handler">handler</glossary> or within an <control_st tag="if">if</control_st> <glossary tag="control structure">control structure</glossary>.</p><p/><p>Use the <b>pass</b> <glossary tag="control structure">control structure</glossary> at the end of a <glossary tag="handler">handler</glossary> to make sure that <glossary tag="object">objects</glossary> further up the <glossary tag="message path">message path</glossary>, or LiveCode itself, receive the <keyword tag="message box">message</keyword>. For example, if a <glossary tag="stack">stack's</glossary> <property tag="script">script</property> contains a <message tag="closeCard">closeCard</message> <glossary tag="handler">handler</glossary> that does housekeeping tasks, and a particular <keyword tag="card">card</keyword> needs to perform additional tasks if the <object tag="stack">stack</object> is closed when on that <keyword tag="card">card</keyword>, the <glossary tag="card">card's</glossary> <message tag="closeCard">closeCard</message> <glossary tag="handler">handler</glossary> can perform those additional tasks, and then use the <b>pass</b> <glossary tag="control structure">control structure</glossary> to let the <message tag="closeCard">closeCard</message> <glossary tag="handler">handler</glossary> in the <glossary tag="stack">stack's</glossary> <property tag="script">script</property> receive the message and be <glossary tag="execute">executed</glossary>. The following example demonstrates the idea:</p><p/><p><code>  on closeCard </code><code><i>-- in card script</i></code></p><p><code>    put empty into field "Search"</code></p><p><code>    pass closeCard </code><code><i>-- give stack script a crack at it</i></code></p><p><code>  end closeCard</code></p><p/><p>Built-in messages that perform a task, such as <b>keyDown</b> and <message tag="closeStackRequest">closeStackRequest</message>, must be received by the <glossary tag="engine">engine</glossary> or the task will not be performed. For example, LiveCode enters a typed character into a <keyword tag="field">field</keyword> when it receives the <message tag="keyDown">keyDown</message> <keyword tag="message box">message</keyword>, and starts closing a <object tag="stack">stack</object> when it receives the <message tag="closeStackRequest">closeStackRequest</message> <keyword tag="message box">message</keyword>. For this reason, if you create a <glossary tag="handler">handler</glossary> for a <href tag="../dictionary/builtdashin_message.xml">built-in message</href> that performs a task, make sure to use the <b>pass</b> <glossary tag="control structure">control structure</glossary> to ensure that the <glossary tag="engine">engine</glossary> receives the <keyword tag="message box">message</keyword> after the <glossary tag="handler">handler</glossary> is finished with it.</p><p/><p>Similarly, if you set a custom property, the <b>setProp</b> <glossary tag="trigger">trigger</glossary> must be received by the <glossary tag="engine">engine</glossary>, or the <property tag="customProperties">custom property</property> will not be set. This means that if you create a <control_st tag="setProp">setProp</control_st> <glossary tag="handler">handler</glossary> to intercept requests to set a <property tag="customProperties">custom property</property>, the <glossary tag="property">property</glossary> is not set unless you include a <b>pass</b> <glossary tag="control structure">control structure</glossary> in the <control_st tag="setProp">setProp</control_st> <glossary tag="handler">handler</glossary>.</p><p/><p>When a handler executes a <b>pass</b> <glossary tag="statement">statement</glossary>, the <keyword tag="message box">message</keyword> is <glossary tag="pass">passed</glossary> to the next <glossary tag="object">object</glossary> in the <glossary tag="message path">message path</glossary>. If you use the<code> pass...to top </code>form of the <b>pass</b> <glossary tag="control structure">control structure</glossary>, the <keyword tag="message box">message</keyword> is <glossary tag="pass">passed</glossary> directly to the <glossary tag="engine">engine</glossary>, without being <glossary tag="pass">passed</glossary> through any other <glossary tag="object">object</glossary> in the <glossary tag="message path">message path</glossary>.</p><p/><p>To halt the current handler without passing the message on through the message path, use the <b>exit</b> <glossary tag="control structure">control structure</glossary> instead. To halt the current <glossary tag="handler">handler</glossary> and return a result, use the <constant tag="return">return</constant> <glossary tag="control structure">control structure</glossary> instead.</p><p/><p><code/><img src="202653"/> <b>Important!</b><code/> You cannot use the <control_st tag="pass">pass</control_st> <glossary tag="command">command</glossary> to pass a <keyword tag="message box">message</keyword> that was originally sent with the <command tag="send">send</command> <glossary tag="command">command</glossary>.</p><p/><p><b>Changes:</b></p><p>The<code> pass...to top </code>form was added in version 2.1.</p>
  </description>
</doc>