Messages

Messages are part of the internal workings of the LiveCode language that are not readily seen. However they are very important because they determine which handlers are executed. Many of those messages are generated by LiveCode itself in response to events. As a result LiveCode is called an event-driven language. To see a big list of such built-in messages, check out this Message list.

Custom messages can also be created by the programmer. Both built-in messages and custom messages are handled the same way by LiveCode. When any message finds a handler or function by the same name, that function or handler is executed.

Message Path

When a message is generated, that message follows a particular path checking the handlers and functions in various objects along the way. This is called the message path. The following shows the standard message paths:

Message path

• Messages - When LiveCode sends a message to an object, that message travels up the message path toward the LiveCode engine. If the message makes it all the way to the engine, then the default action for that message is done. If the message first finds a message handler or function by the same name, then that function or handler is executed. In other words, a handler or a function stops a message from going any further up the message path. This is also called "trapping" a message.
• Pass - Normally, the execution of a handler or function stops the message from traveling further up the message path. However, if that handler contains the pass keyword, the message is released from that handler and continues on up the message path as before. Suppose a button contains the following mouseUp handler:

on mouseUp                     -- This handler is executed when button is clicked
  answer "This is a click"     -- answer = "This is a click"
  pass mouseUp                 -- "mouseUp" message passed along message path
end mouseUp                    -- end of mouseUp handler

When the user clicks on the button, LiveCode sends a mouseUp message to the button. The mouseUp message finds the above handler and it is executed. This mouseUp handler responds with "This is a click". Then the "mouseUp" message is passed along to the card and further up the message path toward the engine. If another mouseUp handler is found, it will be executed.

• Order of execution - If there are two or more handlers that could be executed by a message, its the one encountered first on the message path that will be executed. Unless there is a pass keyword, the rest will never see the message and so are never executed. The handler's placement on the message path determines which handler gets executed.

• Custom Messages - The programmer can create a custom message in the handler of an object. If that handler is executed, then the custom message will then travel up the rest of the message path toward the engine. If a handler or function of that same name is found, it will be executed. For example, suppose the following handler is created in a button:

on mouseUp                   -- This handler is executed when button clicked
  newMessage                 -- This is a custom message
end mouseUp                  -- end of mouseUp handler

When the user clicks on this button, LiveCode sends a mouseUp message to the button. The mouseUp message finds the mouseUp handler and it is executed. That handler creates a custom message, called "newMessage". That message will continue following the message path from the button to the card and from there up toward the engine. If a handler called newMessage is found anywhere on the message path, that handler is executed.

Changing the Message Path

• Send - A programmer can route a message directly to a particular object. That object is identified as the target. The message follows up the message path of that object towards the engine. If any handler by that same name is found on the message path, it is executed within the context of the target. Any message (whether built-in or custom) can be sent using the send command. For example:

send "message" to object                     -- general form of send command
send "mouseDown" to stack "MySpecialStack"   -- "mouseDown" message sent to stack
send "doMyFunct" to group "myObligingGroup"  -- "doMyFunct" message sent to group 

The above "mouseDown" message would be sent to the stack "MySpecialStack". If the stack contains a mouseDown handler, then it is executed. If not the message continues on up the message path toward the engine. The above "doMyFunct" message would be sent to the group "myObligingGroup". If the group contains a doMyFunct handler, then it is executed. If not the message continues on up the message path toward the engine.

• Call - The call command does the same as the send command, except that when the handler is executed, the context remains with the object containing the call command. For example:

call "message" to object                       -- general form of call command
call "mouseUp" to group "MySpecialGroup"       -- "mouseUp" message sent to group
send "doAFunction" to field "anObligingField"  -- "doAFunction" message sent to field

The above mouseUp message would be sent to the group "MySpecialGroup". If the group contains a mouseUp handler, then it is executed. If not the message continues on up the message path toward the engine. The above doAFunction message would be sent to the field "anObligingField". If the field contains a doAFunction handler, then it is executed. If not, the message continues on up the message path toward the engine.

• Behavior - Sometimes it important to provide several objects with the same handlers. The source of the handlers is called the behavior object, it must be a stack or a button. The behavior of any card control should be set to the long ID of the behavior object. When that happens, the message path changes so that it goes from the card control to the behavior object and then on up its message path. By default, the behavior of a newly created objects is empty.

Suppose the behavior object is button "MadMax". And suppose we have a field "Fred" we want to inherit the handlers of MadMax. This is done in coding by executing the following:

set the behavior of field "Fred" to long ID of button "MadMax"

Then, when a message is sent to field "Fred", it becomes the target. The message will continue on to button "MadMax" and then follow that button's message path toward the engine.

Extending the Message Path

• Libraries - A Library is a stack with many useful handlers. The programmer can add a library into the message path just after the main stack by the start using command. You can use any number of libraries. The last library added, is the first of them to receive a message. You can remove a library by using the stop using command. For example:

start using stack "GoodStack"  -- insert library after main stack in message path
start using stack "HotRod"     -- insert library after main stack before GoodStack
stop using stack "GoodStack"   -- remove library GoodStack from message path

• Front Scripts - The script of an object may contain many useful handlers. The programmer can place it before all other objects in the message path by using the insert script command. The script of any object can be used. You can use any number of such objects. The last such object added is the first of them to receive the message. You can remove the script of such an object by using the remove script command. For example:

insert script of field "MineAllMine" into front  -- insert field before all objects
insert script of button "Yours" into front       -- insert button before field
remove script of field "MineAllMine" from front  -- remove field from message path

• Back Scripts - The script of an object may contain many useful handlers. The programmer can place it after all other objects in the message path by using the insert script command. The script of any object can be used. You can use any number of such objects. The last such object added is the first of them to receive the message. You can remove the script of such an object by using the remove script command. For example:

insert script of button "Yours2" into back       -- insert button after all objects
insert script of card "MineAlso" into back       -- insert card before button
remove script of button "MYours2" from back      -- remove button from message path