<doc>
	<legacy_id>1683</legacy_id>
	<name>send</name>
	<type>command</type>

	<syntax>
		<example>send <i>message</i> [ to <i>object</i> [in <i>time</i> [seconds | ticks | milliseconds]] ]</example>
	</syntax>

	<synonyms>
	</synonyms>

	<summary>Sends a <keyword tag="message box">message</keyword> to an <glossary tag="object">object</glossary>. </summary>

	<examples>
<example>send "mouseDown" to button "next"</example>
<example>send "mouseDown" to button "text" of stack "project2"</example>
<example><p># A simple timer using send example</p><p></p><p>local sTime</p><p>on mouseUp</p><p>   put 0 into sTime</p><p>   send "timerIncrement" to me in 1 seconds</p><p>end mouseUp</p><p></p><p>on timerIncrement</p><p>   add 1 to sTime</p><p>   put sTime</p><p>   send "timerIncrement" to me in 1 seconds</p><p>end timerIncrement</p></example>
	</examples>

	<history>
		<introduced version="1.0">Added. </introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		
		<experimental version=""></experimental>
		<nonexperimental version=""></nonexperimental>
	</history>

	<objects>
	</objects>

	<platforms>
		<mac/>
		<windows/>
		<linux/>
		<ios/>
		<android/>
	</platforms>

	<classes>
		<desktop/>
		<server/>
		<web/>
		<mobile/>
	</classes>

	<security>
	</security>


	<classification>
	</classification>

	<references>
		<command tag="cancel">cancel Command</command>
		<command tag="call">call Command</command>
		<command tag="debugDo">debugDo Command</command>
		<command tag="dispatch">dispatch Command</command>
		<property tag="callbacks">callbacks Property</property>
		<property tag="backgroundBehavior">backgroundBehavior Property</property>
	</references>

	<description>
	<overview>Use the <b>send</b> <glossary tag="command">command</glossary> to override the normal <glossary tag="message path">message path</glossary>, or to delay a <glossary tag="command">command</glossary> until a specified time. </overview>

		<parameters>
<parameter>
<name>message</name>
<description>An expression that evaluates to a message name, possibly including parameters.</description>
</parameter>

<parameter>
<name>object</name>
<description>Any object reference. If you don't specify an object, the message is set to the object whose handler contains the send command. If you specify a time, you must also specify an object. </description>
</parameter>

<parameter>
<name>time</name>
<description>An integer. If you don't specify a unit of time, the default of ticks is used.</description>
</parameter>		</parameters>

	<value></value>
	<comments>The <i>message</i> can be either the name of a <glossary tag="handler">handler</glossary> or a <glossary tag="LiveCode">LiveCode</glossary> <glossary tag="statement">statement</glossary>. If the <i>message</i> is a <glossary tag="literal string">literal string</glossary> containing more than one <keyword tag="word">word</keyword> (for example, if it includes <glossary tag="parameter">parameters</glossary>, or if it is a multi-word command), it must be enclosed in <glossary tag="double quote">double quotes</glossary>. <p></p><p>Any parameters are evaluated before they are passed to the <b>send</b> <glossary tag="command">command</glossary>. For example, the following statement sends the <message tag="mouseUp">mouseUp</message> <keyword tag="message box">message</keyword> with 2 as the first parameter:</p><p></p><p>  send "mouseUp 1+1" to button "Example"</p><p></p><p>When the send command is used the stack containing the target handler temporarily becomes the defaultStack. All object references in the <i>message</i> are <glossary tag="evaluate">evaluated</glossary> in the current context i. e. the defaultStack. Therefore references within the message that refer to "this card" or "this stack" will be referring to the card or stack where the target handler is located. </p><p></p><p>If you specify a <i>time</i>, the <i>message</i> is sent to the <glossary tag="object">object</glossary> after the specified time has elapsed. The <keyword tag="message box">message</keyword> is added to the <function tag="pendingMessages">pendingMessages</function> <control_st tag="function">function</control_st>. The ID of the <keyword tag="message box">message</keyword> is <glossary tag="return">returned</glossary> by the <function tag="result">result</function> <control_st tag="function">function</control_st>. To cancel the <keyword tag="message box">message</keyword>, use the <b>cancel</b> <glossary tag="command">command</glossary> with this ID. </p><p></p><p></p><important> Specifying a <i>time</i> can affect the order in which <glossary tag="statement">statements</glossary> are <glossary tag="execute">executed</glossary>. If you don't specify a <i>time</i>, the <i>message</i> is sent immediately, and any <glossary tag="handler">handler</glossary> it <glossary tag="trigger">triggers</glossary> is completed before the rest of the current <glossary tag="handler">handler</glossary> is <glossary tag="execute">executed</glossary>. If you use the send in time form of the <b>send</b> <glossary tag="command">command</glossary>--even if you specify a <i>time</i> of zero seconds--the current handler finishes <glossary tag="execute">executing</glossary> before the <glossary tag="message">message</glossary> is sent.</important><p></p><p></p><note> Using the <b>send</b> <glossary tag="command">command</glossary> is slower than directly <glossary tag="execute">executing</glossary> the <glossary tag="command">commands</glossary> using the normal <glossary tag="message path">message path</glossary>. For best efficiency, use the <b>send</b> <glossary tag="command">command</glossary> only when you want to delay the <glossary tag="message">message</glossary> or when the <glossary tag="handler">handler</glossary> you want to execute is not in the <glossary tag="message path">message path</glossary>.</note></comments>
	</description>
</doc>