<doc>
	<legacy_id>1591</legacy_id>
	<name>on</name>
	<type>control structure</type>

	<syntax>
		<example>on <i>messageName </i>[<i>parametersList</i>] <i>statementList</i> end <i>messageName</i></example>
	</syntax>

	<synonyms>
		<synonym>command</synonym>
	</synonyms>

	<summary>Defines a <glossary tag="message handler">message handler</glossary>.</summary>

	<examples>
<example><p>on resizeStack pNewWidth, pNewHeight</p><p>  set the rect of field "Background" of me to the rect of card 1 of me</p><p>end resizeStack</p></example>
<example><p>command processData pData</p><p>  -- Do some work</p><p>end processData</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>
		<category>Writing LiveCode</category>
	</classification>

	<references>
		<function tag="commandNames">commandNames Function</function>
		<function tag="result">result Function</function>
		<function tag="paramCount">paramCount Function</function>
		<command tag="dispatch">dispatch Command</command>
		<keyword tag="end">end Keyword</keyword>
		<keyword tag="private">private Keyword</keyword>
		<control_st tag="exit">exit Control Structure</control_st>
	</references>

	<description>Use the <b>on</b> <glossary tag="control structure">control structure</glossary> to <glossary tag="handle">handle</glossary> a <keyword tag="message box">message</keyword>, or to implement a custom command.<p></p><p><b>Form:</b></p><p>The first line of a message handler consists of the word "on" followed by the message's name. If the handler has any parameters, their names come after the message name, separated by commas.</p><p></p><p>The last line of a message handler consists of the word "end" followed by the handler's name.</p><p></p><p><b>Parameters:</b></p><p>The <i>messageName</i> is the name of the handler. The <i>messageName</i> must not be a <glossary tag="LiveCode">LiveCode</glossary> <glossary tag="reserved word">reserved word</glossary>.</p><p></p><p>The <i>parametersList</i> consists of one or more <glossary tag="parameter">parameter</glossary> names, separated by commas.</p><p></p><p>The <i>statementList</i> consists of one or more <glossary tag="LiveCode">LiveCode</glossary> <glossary tag="statement">statements</glossary>.</p><p></p><p><b>Comments:</b></p><p>The purpose of a message handler is to perform an action, or actions, when the message is received.</p><p></p><p>A message handler can contain any set of LiveCode statements.</p><p></p><p>The <i>messageName</i> is the name of the <keyword tag="message box">message</keyword> to be <glossary tag="handle">handled</glossary>. This can be either a built-in <keyword tag="message box">message</keyword> (such as <message tag="mouseDown">mouseDown</message> or <message tag="openCard">openCard</message>) or a <keyword tag="message box">message</keyword> that triggers a custom command <glossary tag="handler">handler</glossary>. In either case, when a <keyword tag="message box">message</keyword> called <i>messageName</i>, traversing the <glossary tag="message path">message path</glossary>, arrives at an <glossary tag="object">object</glossary>, LiveCode checks that <glossary tag="object">object's</glossary> <property tag="script">script</property> to see whether it has a <glossary tag="message handler">message handler</glossary> corresponding to the <keyword tag="message box">message</keyword>. If it does, the <glossary tag="statement">statements</glossary> in that <glossary tag="message handler">message handler</glossary> are <glossary tag="execute">executed</glossary>.</p><p></p><p>You create a custom command by writing an <b>on</b> <glossary tag="message handler">message handler</glossary> for it. When you use the <glossary tag="command">command</glossary> in a <property tag="script">script</property>, a <keyword tag="message box">message</keyword> corresponding to that <glossary tag="command">command</glossary> is <glossary tag="pass">passed</glossary> through the <glossary tag="message path">message path</glossary>. When it reaches the <glossary tag="object">object</glossary> whose <property tag="script">script</property> contains the <b>on</b> <glossary tag="handler">handler</glossary>, the <glossary tag="statement">statements</glossary> in the <glossary tag="handler">handler</glossary> are <glossary tag="execute">executed</glossary>.</p><p></p><p></p><p></p><p></p><note>If you want to declare a handler that is local to the script it is contained in then you can use the <keyword tag="private">private keyword</keyword>, please see the dictionary entry for the <keyword tag="private">private keyword</keyword> for more information</note><p></p><p></p><p></p><p></p><note>As the <function tag="result">result</function> is a global property, if you do not explicitly <control_st tag="return">return</control_st> a value, then <function tag="result">the result</function> will no change, but reflect the last engine command, engine function or command or function handler that did return a value.</note><p></p><p></p><p></p><p></p><change></change>The <b>command </b>synonym, along with the ability to declare private handlers was added in LiveCode 2.8.1</description>
</doc>