Name: on

Type: control structure

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

Summary: Defines a <message handler>.

Synonyms: command

Introduced: 1.0

OS: mac,windows,linux,ios,android

Platforms: desktop,server,web,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>, 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> 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: script (property), object (object), mouseDown (message), openCard (message), end (keyword), private (keyword), exit (control_st), return (control_st), result (function), commandNames (function), paramCount (function), the result (function), dispatch (command), handle (glossary), handler (glossary), execute (glossary), message handler (glossary), private keyword (glossary), pass (glossary), message path (glossary), control structure (glossary), message (glossary), command (glossary), statement (glossary)
