<doc>
	<legacy_id>1247</legacy_id>
	<name>return</name>
	<type>control structure</type>

	<syntax>
		<example>return <i>value</i></example>
	</syntax>

	<synonyms>
	</synonyms>

	<summary>Stops the current <glossary tag="handler">handler</glossary> and <glossary tag="return">returns</glossary> a <function tag="value">value</function> to the <glossary tag="handler">handler</glossary> that <glossary tag="call">called</glossary> the current <glossary tag="handler">handler</glossary>. Sets the result to the value as well</summary>

	<examples>
	</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>
		<category>Writing LiveCode</category>
	</classification>

	<references>
		<function tag="merge">merge Function</function>
		<function tag="result">result Function</function>
		<control_st tag="exit">exit Control Structure</control_st>
		<control_st tag="throw">throw Control Structure</control_st>
	</references>

	<description>Use the <b>return</b> <glossary tag="control structure">control structure</glossary> to <constant tag="return">return</constant> a <function tag="value">value</function> from a custom function or <control_st tag="getProp">getProp</control_st> <glossary tag="handler">handler</glossary>, or to <constant tag="return">return</constant> an error message from a <glossary tag="message handler">message handler</glossary> or <control_st tag="setProp">setProp</control_st> <glossary tag="handler">handler</glossary>.<p>The <b>return</b> control structure set <function tag="result">the result</function> to the value being returned.</p><p></p><p><b>Form:</b></p><p>The <b>return</b> <glossary tag="statement">statement</glossary> appears on a line by itself, anywhere inside a <glossary tag="handler">handler</glossary>.</p><p></p><p><b>Parameters:</b></p><p>The <i>handler</i> is the name of the <glossary tag="handler">handler</glossary> in which the <b>return</b> <glossary tag="control structure">control structure</glossary> appears.</p><p></p><p><b>Comments:</b></p><p>When the <b>return</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>return</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><p>If the <b>return</b> <glossary tag="control structure">control structure</glossary> is within a <control_st tag="function">function</control_st> or <control_st tag="getProp">getProp</control_st> <glossary tag="control structure">control structure</glossary>, the <i>value</i> is returned to the <glossary tag="caller">calling handler</glossary> as the <control_st tag="function">function</control_st> <function tag="value">value</function> or <glossary tag="property">property</glossary> setting. For example, if you have the following <control_st tag="function">function</control_st> <glossary tag="handler">handler</glossary>:</p><p></p><p></p><p></p><p></p><p></p><p>which is called in the following statement:</p><p></p><p></p><p></p><p>then 1, the value returned by "simpleFunction", is placed in the field.</p><p></p><p>If the <b>return</b> <glossary tag="control structure">control structure</glossary> is within an <control_st tag="on">on</control_st> or <control_st tag="setProp">setProp</control_st> <glossary tag="control structure">control structure</glossary>, the <i>value</i> can be retrieved by checking the <function tag="result">result</function> <control_st tag="function">function</control_st> in the <glossary tag="caller">calling handler</glossary>. Usually, when the <b>return</b> <glossary tag="control structure">control structure</glossary> is used within an <control_st tag="on">on</control_st> or <control_st tag="setProp">setProp</control_st> <glossary tag="control structure">control structure</glossary>, it <glossary tag="return">returns</glossary> an error message. (If you want a <glossary tag="handler">handler</glossary> to compute a <function tag="value">value</function> as its main reason for existence, you should implement it as a custom function rather than a custom command.)</p><p></p><p>When a message handler executes a <b>return</b> <glossary tag="statement">statement</glossary>, the <keyword tag="message box">message</keyword> stops and is not <glossary tag="pass">passed</glossary> to the next <glossary tag="object">object</glossary> in the <glossary tag="message path">message path</glossary>. To halt the current <glossary tag="message handler">message handler</glossary> and <control_st tag="pass">pass</control_st> the <keyword tag="message box">message</keyword> on through the <glossary tag="message path">message path</glossary>, use the <control_st tag="pass">pass</control_st> <glossary tag="control structure">control structure</glossary> instead. To halt the current <glossary tag="handler">handler</glossary> without returning a result, use the <control_st tag="exit">exit</control_st> <glossary tag="control structure">control structure</glossary> instead.</p><p></p><p></p><p></p><note>The <b>return</b> <glossary tag="control structure">control structure</glossary> is implemented internally as a <glossary tag="command">command</glossary> and appears in the <function tag="commandNames">commandNames</function>.</note><p></p><p></p><p></p><note>As well as the <b>return</b> <glossary tag="control structure">control structure</glossary> returns the value to the caller, it sets <function tag="result">the result</function> to the value</note></description>
</doc>