Commands

Message Handlers are commonly called Handlers or Commands. LiveCode has many built-in Handlers, a list of them is found at the end of this article. A programmer can create their own Handlers, called Custom Handlers. This article is mainly about how to structure and use Custom Handlers.

A Custom Message Handler is very similar to a Custom Function Handler. But there are differences, so don't confuse the two. However, which one you use usually comes down to personal preference. See also Function Handlers.

Structure[]

The first line of a Custom Handler must start with the word "on", followed my the name of the of the Handler. That name is also the name of the message which causes its execution. If there are any handler parameters, they are placed as a list of items after the name of the Handler. The last line of a Handler must start with the word "end", followed by the name of the Handler.

Between the first and the last line of the Handler are the list of statements that make up the Handler. The statement list may include one or more Return statements, or none. The first Return statement that is executed stops the Handler execution and returns the value, it is the effective end of the Handler. Otherwise, when the end statement is executed, that is the end of the Handler.

A Handler example:

on myWeek theDays                              -- myWeek has one parameter: theDays 
  return theDays + 7                           -- 7 is added to theDays, then it is
end myWeek                                     -- returned to the calling statement.

Calling Statement[]

The Calling Statement starts with the name of the Handler. If there are any parameters, they are placed as a list of items after the name of the Handler in the Calling Statement. The parameter list in the Calling statement should match the parameter list in the Handler in order. Each parameter in the parameter list of the Calling Statement must be an appropriate value or a variable containing the appropriate value. The Calling Statement is placed on a line by itself in any other handler. That handler would then be known as the Calling handler.

A Calling handler for the example above:

on mouseUp                             -- mouseUp handler
  myWeek 4                             -- myWeek is called
  put the result into thisWeek         -- thisWeek = 11
  answer "myWeek = " & thisWeek        -- answer shows myWeek = 11
end mouseUp                            -- end mouseUp handler

When the Calling Statement is executed, the name and parameter list becomes the message which travels along the message path towards to LiveCode engine. If the message encounters an appropriate handler, then it is executed.

If a value is returned by the Handler, it is returned in a variable called "the result." The value of the result should be stored in another variable soon after it is returned, because the result changes value after the execution of every handler or function. Therefore save its value before it changes.

Another Handler example

on Fred george, bob, dude         -- george 1st number, bob the 2nd and dude the 3rd
  put george + bob - dude into Temp    -- Temp = 1st + 2nd - 3rd
  return Temp                          -- Temp is returned to the calling statement
end Fred                               -- end Fred function

The Calling handler for above:

on mouseUp                             -- This is the calling handler mouseUp
  Fred 4,5,6                           -- Fred is called
  put the result into Susan            -- Susan = 3
end mouseUp                            -- end mouseUp handler

Private Handlers[]

A Private Handler is placed in the same script as the Calling handler. When LiveCode executes a Calling Statement, it sends the message to the local script first. If a Private Handler is encountered, then LiveCode executes that Private Handler. The message doesn't travel far.

The first line of a Private Handler must start with the word "private", followed by the word "command", followed by the name of the Handler. If there are any handler parameters, they are placed as a list of items after the name of the Handler. The parameter list of a Private Handler operates the same as the parameter list of any Handler.

Common Built-in Handlers[]

Please help to complete this list

Commands

Contents

Structure[]

Calling Statement[]

Private Handlers[]

Common Built-in Handlers[]

Fan Feed