Name: pass

Type: control structure

Syntax: pass <messageName> [to top]

Summary:

Stops the current <handler> and <pass|passes> the <message> to the next

<object(glossary)> in the <message path>.

Introduced: 1.0

OS: mac, windows, linux, ios, android

Platforms: desktop, server, mobile

Parameters:

messageName:

The name of the handler in which the pass control structure appears.

Description:

Use the <pass> <control structure> to end a <handler> while letting the

<message> continue along the <message path>.

**Form:** The <pass> <statement> appears on a line by itself, anywhere

inside a <handler>.

When the <pass> <control structure> is <execute|executed>, any remaining

<statement|statements> in the <handler> are skipped. Hence, the <pass>

<control structure> is usually used either at the end of a <handler> or

within an <if> <control structure>.

Use the <pass> <control structure> at the end of a <handler> to make

sure that <object|objects> further up the <message path>, or LiveCode

itself, receive the <message>. For example, if a <stack|stack's>

<script> contains a <closeCard> <handler> that does housekeeping tasks,

and a particular <card(keyword)> needs to perform additional tasks if

the <stack> is closed when on that <card(keyword)>, the

<card(object)|card's> <closeCard> <handler> can perform those additional

tasks, and then use the <pass> <control structure> to let the

<closeCard> <handler> in the <stack|stack's> <script> receive the

message and be <execute|executed>. The following example demonstrates

the idea:

on closeCard -- in card script

put empty into field "Search"

pass closeCard -- give stack script a crack at it

end closeCard

Built-in messages that perform a task, such as keyDown and

<closeStackRequest>, must be received by the <engine> or the task will

not be performed. For example, LiveCode enters a typed character into a

<field> when it receives the <keyDown> <message>, and starts closing a

<stack> when it receives the <closeStackRequest> <message>. For this

reason, if you create a <handler> for a <built-in message> that performs

a task, make sure to use the <pass> <control structure> to ensure that

the <engine> receives the <message> after the <handler> is finished with

it.

Similarly, if you set a custom property, the setProp <trigger> must be

received by the <engine>, or the <custom property> will not be set. This

means that if you create a <setProp> <handler> to intercept requests to

set a <custom property>, the <property> is not set unless you include a

<pass> <control structure> in the <setProp> <handler>.

When a handler executes a <pass> <statement>, the <message> is

<pass|passed> to the next <object(glossary)> in the <message path>. If

you use the pass...to top form of the <pass> <control structure>, the

<message> is <pass|passed> directly to the <engine>, without being

<pass|passed> through any other <object(glossary)> in the

<message path>.

To halt the current handler without passing the message on through the

message path, use the <exit> <control structure> instead. To halt the

current <handler> and return a result, use the <return>

<control structure> instead.

>*Important:* You cannot use the <pass> <command> to pass a <message>

> that was originally sent with the <send> <command>.

Changes:

The pass...to top form was added in version 2.1.

References: call (command), send (command), return (constant),

pass (control structure), exit (control structure),

setProp (control structure), if (control structure), pass (glossary),

engine (glossary), built-in message (glossary), property (glossary),

statement (glossary), execute (glossary), command (glossary),

control structure (glossary), trigger (glossary),

custom property (glossary), message path (glossary), field (glossary),

message (glossary), script (glossary), handler (glossary),

object (glossary), end (keyword), card (keyword), closeCard (message),

closeStackRequest (message), keyDown (message), stack (object),

card (object), dynamicPaths (property), backgroundBehavior (property)

Tags: messages