The message path is the set of rules that determine which objects, in which order, have the opportunity to respond to a message. The message path is based on the object hierarchy.

Each LiveCode object is part of another object, of a different object type. For example, each card is part of a stack, each grouped control is part of a group, and so on. This object hierarchy defines the ownership and inheritance relationship between objects.

When a message is sent to an object, it is often handled directly by a message handler in that object. However if no handler is present, the message continues along a path until it finds a message handler that can respond to it. The object hierarchy is closely related to the path that a message travels on. In most cases, when an object passes a message on, the message goes to the object's owner in the object hierarchy.

For example, suppose the user clicks a button in a main stack, causing LiveCode to send a mouseUp message to the button. If the button's script does not contain a handler for the mouseUp message, the message is passed along to the card the button is on. If the card's script contains a mouseUp handler, the handler is executed. But if the card does not handle the mouseUp message, it is passed on to the card's stack. If the stack script contains a mouseUp handler, the handler is executed. But if the stack does not handle the mouseUp message, it is passed on to the engine.

The engine is the end of the message path, and if a message reaches it, the engine takes any default action (e.g. inserting a character into a field or highlighting a button), then throws the message away.

In this example we have a button, which is in a group, on a card, that is part of a stack.

When the button is clicked a mouseUp message is sent to the button, if the button handles the message it logs this in the field and the message does not travel any further.

Button Script

on mouseUp
   put the name of me && "received the mouseUp message" & return after field "log"
end mouseUp

However if the button does not handle the mouseUp message it is passed up the message path, first to the group (which in this case does not handle the message) and then to the card which handles the message.

Card Script

on mouseUp
   put the name of me && "received the mouseUp message" & return after field "log"
end mouseUp

An object can handle a message and choose to pass it up the message path anyway, this can be useful if an object higher up the message path also needs to know that an event has occurred.

In this example the button, group and card all receive the message, handle it and pass it on up the message path until it reaches the stack.

Button Script

on mouseUp
   put the name of me && "received the mouseUp message" & return after field "log"
   pass mouseUp
end mouseUp

Group Script

on mouseUp
   put the name of me && "received the mouseUp message" & return after field "log"
   pass mouseUp
end mouseUp

You can find the message path example stack here: http://livecodeshare.runrev.com/stack/605/Message-Path-Example

The Message Path makes it possible to group similar functionality together at different levels within your application. This behavior applies both to event messages sent as a result of a user action, and custom messages sent by script. It is therefore possible to write libraries of common functions.

You can also use the Message Path to minimize repetitive scripting. Imagine you have 3 buttons called "red", "blue" and "green" which change the text color of a field. These buttons all perform the same task so instead of writing a mouseUp handler for each button you can write one mouseUp handler on the card and within it check which button was pressed to see what color the text should be.

This allows you to add more buttons without copying the script and make changes in only one place.

Card Script

on mouseUp
   put the short name of the target into tColour
   set the foregroundColor of field 1 to tColour
end mouseUp