Name: on

Synonyms: command

Type: control structure

Syntax:
[private] on <messageName> [<parametersList>]
   <statementList>
end <messageName>

Summary:
Defines a <message handler>.

Introduced: 1.0

OS: mac, windows, linux, ios, android

Platforms: desktop, server, mobile

Example:
on resizeStack pNewWidth, pNewHeight
  set the rect of field "Background" of me to the rect of card 1 of me
end resizeStack

Example:
command processData pData
  -- Do some work
end processData

Parameters:
messageName:
The name of the handler. The messageName must not be a LiveCode reserved
word. 

parametersList:
The parametersList consists of one or more parameter names, separated by
commas. 

statementList:
The statementList consists of one or more LiveCode statements.

The result:
>*Note:* As the <result> is a global property, if you do not explicitly
> <return> a value, then <the result> will no change, but reflect the
> last engine command, engine function or command or function handler
> that did return a value.

Description:
Use the <on> <control structure> to <handle> a <message>, or to
implement a custom command. 

**Form:** 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.

The last line of a message handler consists of the word "end" followed
by the handler's name.

The purpose of a message handler is to perform an action, or actions,
when the message is received.

A message handler can contain any set of LiveCode statements.

The <messageName> is the name of the <message> to be <handle|handled>.
This can be either a built-in <message> (such as <mouseDown> or
<openCard>) or a <message> that triggers a custom command <handler>. In
either case, when a <message> called <messageName>, traversing the
<message path>, arrives at an <object(glossary)>, LiveCode checks that
<object|object's> <script> to see whether it has a <message handler>
corresponding to the <message>. If it does, the <statement|statements>
in that <message handler> are <execute|executed>.

You create a custom command by writing an <on> <message handler> for it.
When you use the <command> in a <script>, a <message> corresponding to
that <command> is <pass|passed> through the <message path>. When it
reaches the <object(glossary)> whose <script> contains the <on>
<handler>, the <statement|statements> in the <handler> are
<execute|executed>. 

>*Note:* If you want to declare a handler that is local to the script it
> is contained in then you can use the <private> keyword, please see the
> dictionary entry for the <private> keyword for more information

References: dispatch (command), exit (control structure),
return (control structure), result (function), commandNames (function),
paramCount (function), the result (function), object (glossary),
handle (glossary), handler (glossary), execute (glossary),
message handler (glossary), pass (glossary), message path (glossary),
control structure (glossary), message (glossary),
command (glossary), statement (glossary), end (keyword),
private (keyword), mouseDown (message), openCard (message),
script (property)

