Difference between revisions of "Touch start"

From Second Life Wiki
Jump to navigation Jump to search
m (added a comment about example script effects and a warning about changing states)
 
(6 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Issues/SVC-3017}}{{LSL_Event|event_id=2|event_delay|event=touch_start
{{LSL_Event|event_id=2|event_delay|event=touch_start
|p1_type=integer
|p1_type=integer
|p1_name=num_detected
|p1_name=num_detected
|p1_desc=Number of agents detected touching during the last clockcycle
|p1_desc=Number of agents detected touching during the last clock cycle
|event_desc=Triggered by the start of agent clicking on task
|event_desc=Triggered by the start of agent clicking on task
|constants
|constants
|spec
|spec
|caveats=* If a prim [[face]] has [[Navigating Shared Media|Shared Media]] enabled and the avatar's viewer supports this feature, LSL scripts will not detect touches on that face. Touches from older clients will be detected.
|caveats=* If a prim [[face]] has [[Navigating Shared Media|Shared Media]] enabled and the avatar's viewer supports this feature, LSL scripts will not detect touches on that face. Touches from older clients will be detected.
|examples=You can use numbers 0 through num_detected - 1 to get detected agent keys:
* The default behavior is: If you have a multi-prim object and the root has a [[touch_start]] handler AND one or more child prims has a [[touch_start]] handler, the root prim's handler will be called when it (the root) or a child without a handler is touched. If you touch a child prim that has a [[touch_start]] handler, it will receive the event and the root prim will not.
<lsl>
** This behavior can be configured with [[llPassTouches]]. After configuring a prim's touch-passing behavior you can delete the script that configured the prim.
|examples=You can use numbers 0 through (<code>num_detected</code>-1) with the various <code>llDetected</code>... functions to get detected agent keys etc. For most purposes, it is adequate to bother only with the first detected toucher e.g. [[llDetectedKey]](0). It is rare (but not impossible) for <code>num_detected</code> to be other than 1.
<source lang="lsl2">
default
default
{  
{  
     touch_start(integer num_detected)
     touch_start(integer num_detected)
     {
     {
         key avatarKey = llDetectedKey(0);
         key   avatarKey = llDetectedKey(0);
         string avatarName = llKey2Name(avatarKey);
         string avatarName = llDetectedName(0);


         // PUBLIC_CHANNEL has the integer value 0
         llInstantMessage(avatarKey, "Hello " + avatarName );
        llWhisper(PUBLIC_CHANNEL, "Touched by " + avatarName + ".");
     }
     }
}
}
</lsl>
</source>
If there is any state change in touch_start event and you click on a prim and release before the state is changed, succeeding [[touch]] and [[touch_end]] events will be discarded from the event queue before entering the new state. It means no touch_* event will occur in this new state until you touch it again. If you drop this script into any prim and click it, you will only see the message "You just started touching me so I'm going to the other state...". When you click it again, you will only see the message "The touch that brought you here just ended so I'm going back to default...".
{{Warning|LSL has a problem with switching states so if you rely on high performance scripts, don't change states but use an integer to change your "mode" or something the like.}}
<lsl>
// check the effect of this script when clicking & holding
// your mouse button for a few seconds when touching the prim


default
{
    touch_start(integer num_detected)
    {
        // PUBLIC_CHANNEL has the integer value 0
        llSay(PUBLIC_CHANNEL,
            "You just started touching me so I'm going to the other state...");
        state other;
    }
}
state other
{
    touch_end(integer num_detected)
    {
        llSay(PUBLIC_CHANNEL,
            "The touch that brought you here just ended so I'm going back to default...");
        state default;
    }
}
</lsl>
|helpers
|helpers
|also_header
|also_header
Line 58: Line 31:
{{LSL DefineRow||[[llSetTouchText]]|}}
{{LSL DefineRow||[[llSetTouchText]]|}}
{{LSL DefineRow||[[llPassTouches]]|}}
{{LSL DefineRow||[[llPassTouches]]|}}
{{LSL DefineRow||[[LlDetectedTouchFace]]|}}
{{LSL DefineRow||[[llDetectedTouchFace]]|}}
{{LSL DefineRow||[[LlDetectedTouchST]]|}}
{{LSL DefineRow||[[llDetectedTouchST]]|}}
{{LSL DefineRow||[[LlDetectedTouchUV]]|}}
{{LSL DefineRow||[[llDetectedTouchUV]]|}}
{{LSL DefineRow||[[LlDetectedTouchPos]]|}}
{{LSL DefineRow||[[llDetectedTouchPos]]|}}
{{LSL DefineRow||[[LlDetectedTouchNormal]]|}}
{{LSL DefineRow||[[llDetectedTouchNormal]]|}}
{{LSL DefineRow||[[LlDetectedTouchBinormal]]|}}
{{LSL DefineRow||[[llDetectedTouchBinormal]]|}}
|also_articles
|also_articles
|also_footer
|also_footer
|notes=*If using a touch to change states be careful about the touch_ event order. On clicking a prim with touch events we trigger touch_start (as), touch (during) and touch_end (as released). The touch_ chain will remain intact until either touch_end is triggered or a new touch_start. If however the script is reset (although there is some doubt as far as this is concerned (see {{Jira|SVC-3017}} for more details) the chain will be cleared. If the script is taken into inventory, deleted or the like, the touch_chain is cleared too. It is not certain whether the behavior is truly a bug or expected.
|notes=*If using a touch to change states be careful about the touch event order. '''The best advice is not to do state changes from within touch_start.''' Add a [[touch_end]] handler and do the state change there. Changing state from within [[touch_start]] can cause the next occurrence of THIS [[touch_start]] code to be missed. 
 
*On clicking a prim with touch event handlers, the following handlers are triggered: [[touch_start]] (on first contact), [[touch]] (during) and [[touch_end]] (as released).  
|mode
|mode
|deprecated
|deprecated
Line 72: Line 47:
|cat2=Detected
|cat2=Detected
|cat3=Grab
|cat3=Grab
|cat4
|cat4=Passable
}}
}}

Latest revision as of 21:46, 1 January 2016

Description

Event: touch_start( integer num_detected ){ ; }

Triggered by the start of agent clicking on task

• integer num_detected – Number of agents detected touching during the last clock cycle

Caveats

  • If a prim face has Shared Media enabled and the avatar's viewer supports this feature, LSL scripts will not detect touches on that face. Touches from older clients will be detected.
  • The default behavior is: If you have a multi-prim object and the root has a touch_start handler AND one or more child prims has a touch_start handler, the root prim's handler will be called when it (the root) or a child without a handler is touched. If you touch a child prim that has a touch_start handler, it will receive the event and the root prim will not.
    • This behavior can be configured with llPassTouches. After configuring a prim's touch-passing behavior you can delete the script that configured the prim.


Examples

You can use numbers 0 through (num_detected-1) with the various llDetected... functions to get detected agent keys etc. For most purposes, it is adequate to bother only with the first detected toucher e.g. llDetectedKey(0). It is rare (but not impossible) for num_detected to be other than 1. 

default
{ 
    touch_start(integer num_detected)
    {
        key    avatarKey  = llDetectedKey(0);
        string avatarName = llDetectedName(0);

        llInstantMessage(avatarKey, "Hello " + avatarName );
    }
}

Notes

  • If using a touch to change states be careful about the touch event order. The best advice is not to do state changes from within touch_start. Add a touch_end handler and do the state change there. Changing state from within touch_start can cause the next occurrence of THIS touch_start code to be missed.
  • On clicking a prim with touch event handlers, the following handlers are triggered: touch_start (on first contact), touch (during) and touch_end (as released).

Deep Notes

Signature

event void touch_start( integer num_detected );
Retrieved from "https://wiki.secondlife.com/w/index.php?title=Touch_start&oldid=1198691"