How to send messages to an object using the send command

Sending messages to objects is an important part of the LiveCode language and allows you to write code in an object-orientated manner. This lesson explains the various ways to send messages to objects using a simple example. Note that you can also send messages to objects using the dispatch command. See the documentation for the dispatch command for more information about the differences between these two methods of message sending.

Create a stack and drag a field onto it

Create a stack and drag a field onto it

Using the property inspector (2), name the field "Output" (3). In this lesson, we will use this field as a code "object" by giving it a set of methods and calling them via the LiveCode commands "send" and "dispatch".

Set the field script

Set the field script

Edit the script of the field using the "Code" button in the main LiveCode menu bar. The script contains a number of commands which allow the field's text to be manipulated without directly accessing it. Note that all the handlers are commands rather than functions, it is easier to use commands when sending messages to objects, and its still easy to return values from the commands if needed.

Set the script to the following:

# This command clears the output

command outputClear

put empty into me

end outputClear

# This command writes the string pText to the output

command outputWrite pText

set the text of me to pText

end outputWrite

# This command writes the string pText to the output and gives the output

# the color specified in pColor.

command outputWriteColored pText, pColor

set the htmlText of me to "<p><font color=" & quote & pColor & quote & ">" & pText & "</font></p>"

end outputWriteColored

# This command returns the current value of the output

command outputGet

return the text of me

end outputGet

# This command writes an array to the output

command outputWriteArray pArray

local tOutput

repeat for each key tKey in pArray

put tKey & " = " & pArray[tKey] & return after tOutput

end repeat

set the text of me to tOutput

end outputWriteArray

# This is a private command which cannot be called by using send or dispatch.

private command outputAnswerSomething

answer "This command cannot be called from outside this script because it's private"

end outputAnswerSomething

Using the send command to call a handler

Using the send command to call a handler

The basic form of the send command is:

send message to object

It is also possible to send messages after a certain period of time, but this is a more advanced topic that will not be covered in this lesson.

The simplest example in our stack is the "outputClear" command, which takes no parameters and just empties the field. To call this command we create a button called "Clear", and set its script to the following:

on mouseUp

send "outputClear" to field "Output"

end mouseUp

Passing parameters with the send command

Passing parameters with the send command

There are a few different ways to pass parameters using the send command. I always use the method below as it is very clear and allows any kind of values to be passed (including arrays and long strings full of various symbols).

Below are three examples showing how to send messages with parameters. To try each example out, simply create a button in the stack, and set its script to the code shown.

This example shows how to call the "outputWrite" method of the field to put some text into it:

on mouseUp

local tValue

ask "Please enter some text"

if the result is "cancel" then

exit mouseUp

end if

put it into tValue

# Note here the tValue is inside the quotes, but LiveCode will still process

# it correctly and send the expected value to the command.

send "outputWrite tValue" to field "Output"

end mouseUp

This example shows how to call the "outputWriteColored" method, demonstrating how to pass multiple parameters:

on mouseUp

local tValue

ask "Please enter some text"

if the result is "cancel" then

exit mouseUp

end if

put it into tValue

local tColor

put "#00FF00" into tColor

send "outputWriteColored tValue, tColor" to field "Output"

end mouseUp

This example shows how to call the "outputWriteArray" method, passing an array as a parameter:

on mouseUp

local tArray

put "Value 1" into tArray["Key 1"]

put "Value 2" into tArray["Key 2"]

put "Value 3" into tArray["Key 3"]

send "outputWriteArray tArray" to field "Output"

end mouseUp

Retrieving a value from an object using the send command

A simple way to obtain a value from a object is to send a message to it, then check for the result. For example:

on mouseUp

local tOutput

send "outputGet" to field "Output"

put the result into tOutput

answer "The output is : " & tOutput

end mouseUp

This works because the command "outputGet" returns the value using the line:

return the text of me

Any value can be returned by this method, including arrays.

Sending a message to an object when you don't know the name of the handler

It is still possible to use send when the name of the handler you want to call is in a variable, custom property or has been provided by the user. For example:

on mouseUp

local tMessageName

ask "Please type the name of the message to send to the field"

if the result is "cancel" then

exit mouseUp

end if

put it into tMessageName

if tMessageName is "outputWriteColored" then

local tValue

put "test" into tValue

local tColor

put "#FF0000" into tColor

send tMessageName && "tValue, tColor" to field "Output"

else

send tMessageName to field "Output"

end if

end mouseUp

You may notice that this code will throw an error if you type in the name of a handler that does not exist (or is private). If you are not certain that the target object will handle the message, you can use the dispatch command instead of send, this will allow you to determine whether or not the message was handled with errors being thrown.

 

 

1 Comments

Peter W A Wood

The handler to send a message to an object without knowing its name is missing the code to send the input parameter when sending the "outputWrite" message. This is the modified code that I came up with:

on mouseUp
local tMessageName
ask "Please type the name of the message to send to the field"
if the result is "cancel" then
exit mouseUp
end if
put it into tMessageName

if tMessageName is "outputWriteColored" then
local tValue
put "test" into tValue

local tColor
put "#FF0000" into tColor
send tMessageName && "tvalue, tColor" to field "Output"
else if tMessageName is "outputWrite" then
put "test" into tValue
send tMessageName && "tValue" to field "Output"
else
send tMessageName to field "Output"
end if
end mouseUp

Incidentally, as I understand the scope of local variables declared in a handler is the handler. If I am correct is it really good practice to declare them within statement blocks (eg for, if)? This cold lead somebody to think that the scope of the variable is the block a la C and Java.

Add your comment

E-Mail me when someone replies to this comment