Name: send

Type: command

Syntax: send [script] <message> [ to <object> [in <time> [{seconds | ticks | milliseconds}] ] ]

Syntax: send script <message> [ to <object> ]

Summary:
Sends a <message> to an <object(glossary)>.

Introduced: 1.0

OS: mac, windows, linux, ios, android

Platforms: desktop, server, mobile

Example:
send "mouseDown" to button "next"

Example:
send "mouseDown" to button "text" of stack "project2"

Example:
# A simple timer using send example

local sTime
on mouseUp
   put 0 into sTime
   send "timerIncrement" to me in 1 seconds
end mouseUp

on timerIncrement
   add 1 to sTime
   put sTime
   send "timerIncrement" to me in 1 seconds
end timerIncrement

Example:
send script "answer the short name of me" to stack "Message Box"

Parameters:
message:
An expression that evaluates to a message name, possibly including
parameters. 

object:
Any object reference. If you don't specify an object, the message is set
to the object whose handler contains the send command. If you specify a
time, you must also specify an object.

time (integer):
If you don't specify a unit of time, the default of ticks is used.

The result:
If you specify a <time>, the <message> is sent to the <object(glossary)>
after the specified time has elapsed. The <message> is added to the
<pendingMessages> <function>. The ID of the <message> is
<return|returned> by the <result> <function>. To cancel the <message>,
use the <cancel> <command> with this ID.

Description:
Use the <send> <command> to override the normal <message path>, or to
delay a <command> until a specified time.

The <message> can be either the name of a <handler> or a <LiveCode>
<statement>. If the <message> is a <literal string> containing more than
one <word> (for example, if it includes <parameter|parameters>, or if it
is a multi-word command), it must be enclosed in <double quote|double
quotes>. 

If the `script` form is used, the <message> is simply sent unmodified to the 
<object>. Otherwise, any parameters are evaluated before they are passed to the 
<send> <command>. For example, suppose there is a stack named "Stack" with 
script
    
    on doAnswer pParam
       answer pParam
    end doAnswer

    function myName
       return the short name of me
    end myName
    
and a button on the stack named "Button" with script

    on mouseUp
       send "doAnswer myName()" to this stack
       send script "doAnswer myName()" to this stack
    end mouseUp

    function myName
       return the short name of me
    end myName

clicking the button would result in an answer dialog first saying "Button" as the
`myName` function would be evaluated in the button context, then "Stack" as 
using the `script` form would result in the `myName` function being evaluated in the 
stack context.

When the send command is used the stack containing the target handler
temporarily becomes the defaultStack. All object references in the
<message> are <evaluate|evaluated> in the current context i. e. the
defaultStack. Therefore references within the message that refer to
"this card" or "this stack" will be referring to the card or stack where
the target handler is located.

It is a parse error to specify a time when using the `script` form.

>*Important:*  Specifying a <time> can affect the order in which
> <statement|statements> are <execute|executed>. If you don't specify a
> <time>, the <message> is sent immediately, and any <handler> it
> <trigger|triggers> is completed before the rest of the current
> <handler> is <execute|executed>. If you use the send in time form of
> the <send> <command> --even if you specify a <time> of zero
> seconds--the current handler finishes <execute|executing> before the
> <message> is sent.

>*Note:*  Using the <send> <command> is slower than directly
> <execute|executing> the <command|commands> using the normal 
> <message path>. For best efficiency, use the <send> <command> only when 
> you want to delay the <message> or when the <handler> you want to 
> execute is not in the <message path>.

References: debugDo (command), dispatch (command), call (command),
cancel (command), function (control structure), result (function),
pendingMessages (function), object (glossary), literal string (glossary),
return (glossary), evaluate (glossary), execute (glossary),
command (glossary), LiveCode (glossary), double quote (glossary),
trigger (glossary), message path (glossary), message (glossary),
parameter (glossary), statement (glossary), handler (glossary),
word (keyword), mouseUp (message), callbacks (property),
backgroundBehavior (property)

Tags: messages
