$nav
===== Function: llPassTouches =====

<code lsl2>
llPassTouches(integer pass)
</code>

Indicates whether a child prim in a linkset should let the root know that it has been touched.

When a script in the root prim has one of the touch events ($lev[touch_start], $lev[touch] or $lev[touch_end]) active, the whole object becomes touchable. However, when a child prim has at least one script that has a touch event active and that prim is touched, by default only that prim will receive the touch, and the root will not receive it. This function allows changing that default, so that //both// the root and the child can receive the touches, or so that the root won't receive them even if the child has no active touch events.

This function should be called from a script in a child prim; it has no effect if called from the root prim.

===== Parameters =====

=== pass ===
An $lty[integer] value indicating whether to pass touches to the root.

A value of $lct[PASS_IF_NOT_HANDLED] makes the root receive touches from the child prim the script is in, only if none of the scripts in that child has an active touch event. If there is one, the root won't receive touches; only the child will. This is the default value when no script in the child calls $fn[llPassTouches].

A value of $lct[PASS_ALWAYS] makes the root receive touches from the child prim the script is in, even if a script in that child prim has an active touch event (in which case both will receive it).

A value of $lct[PASS_NEVER] makes the root not receive touches from the child prim the script is in, regardless of the presence or absence of an active touch event in the child.

===== Notes =====

  * The setting only takes place for the prim where the script is in; it doesn't affect any other prims.
  * If there is an active touch event in the child, it will always receive touches, regardless of this setting. It only affects whether the root will receive touches.
  * If the root prim has an active touch event, a touch cursor will be shown for all prims in the linkset, regardless of the setting of this function. In other words, a value of $ct[PASS_NEVER] will not make the hand cursor disappear for the child prim the script is in, even if there's no active touch event in the child.
  * $perscript
     * If the same script calls this function several times, the one that was executed last prevails. If several scripts in the same prim call it, the one with the highest value takes precedence ($ct[PASS_NEVER] has precedence over $ct[PASS_ALWAYS], which has precedence over $ct[PASS_IF_NOT_HANDLED]).
  * What does //active// mean in this case? Touch events are //active// only if the script is running and in a state that has a touch event. If the script stops running, or if the current state has no touch event, there will be no active touch event for that script.

===== Short examples =====

<code lsl2>
llPassTouches(PASS_ALWAYS); // Enables touch passing for this prim.

llPassTouches(PASS_NEVER); // Disables touch passing.

// Disables touch passing if there's an active touch event;
// lets the root receive them if not:
llPassTouches(PASS_IF_NOT_HANDLED);
</code>

===== Complete examples =====

When this simple script is dropped into a child prim that has more scripts, one of them with a touch event, it will let the root know that it has been touched. Imagine, for example, a swing where the seat is a child prim, which has a script that activates a pose menu, and the root has a script that starts and stops swinging, but the seat where the pose menu is, is easier to touch than other prims. In that case, dropping this script into the seat will make both the swing script and the menu activate with a single touch of the seat.

Removing or stopping the script will make the effect disappear.

<file lsl2 llPassTouches-example.lsl>
default
{
    state_entry()
    {
        llPassTouches(PASS_ALWAYS);
    }
}
</file>

\\

The following pair of scripts illustrates the behaviour of the different modes. It will toggle between active and inactive every five seconds, and it will report in chat who receives the touches.

This script goes in a child prim:
<file lsl2 llPassTouches-behaviour-child.lsl>
// Edit the following line to test the different modes
// (use PASS_IF_NOT_HANDLED, PASS_ALWAYS or PASS_NEVER depending
// on what you want to test):
integer Behaviour_to_test = PASS_IF_NOT_HANDLED;

default
{
    state_entry()
    {
        llPassTouches(Behaviour_to_test);
        llSetTimerEvent(5);
        state WithTouch;
    }
}

state WithTouch
{
    state_entry()
    {
        llSetText("This prim has an active touch_end event now.", <1,0,0>, 1);
    }

    touch_end(integer num_touchers)
    {
        llSay(0, "The child prim received the touch.");
    }

    timer()
    {
        state WithoutTouch;
    }
}

state WithoutTouch
{
    state_entry()
    {
        llSetText("This prim has no active touch events now.", <0.4,0.4,0.4>, 1);
    }

    timer()
    {
        state WithTouch;
    }
}
</file>
And this script goes in the root prim:
<file lsl2 llPassTouches-behaviour-root.lsl>
default
{
    touch_end(integer num_touchers)
    {
        llSay(0, "The root received a touch.");
    }
}
</file>

===== See also =====

  * Touch events: $lev[touch_start], $lev[touch], $lev[touch_end].
  * $lfn[llPassCollisions] is similar but for collision events.
  * $lct[PASS_IF_NOT_HANDLED], $lct[PASS_ALWAYS], $lct[PASS_NEVER] constants.