Difference between revisions of "LlSetText"

From Second Life Wiki
Jump to navigation Jump to search
m
(a few readability improvements)
Line 21: Line 21:
**Floating text is a prim property and not dependent on a script for its continued existence.
**Floating text is a prim property and not dependent on a script for its continued existence.
*To remove floating text, use the following:
*To remove floating text, use the following:
<lsl>llSetText("", <1.0, 1.0, 1.0>, 1.0);</lsl>
<lsl>
//  ZERO_VECTOR has the vector value <0.0, 0.0, 0.0>
//  when used as a color it's black
 
    llSetText("", ZERO_VECTOR, 0.0);
</lsl>
*Shift-copying does not keep the floating text prim property. If the llSetText() script is not triggered when a copy made, the copy will not have the floating text.
*Shift-copying does not keep the floating text prim property. If the llSetText() script is not triggered when a copy made, the copy will not have the floating text.
*Vertical whitespace is removed from the end of the text string, so if you want vertical whitespace put any character (like a space) on the last line.
*Vertical whitespace is removed from the end of the text string, so if you want vertical whitespace put any character (like a space) on the last line.
*Multiple linebreaks with empty lines are converted to a single linebreak, so add a whitespace character on every line you want to skip:
*Multiple linebreaks with empty lines are converted to a single linebreak, so add a whitespace character on every line you want to skip:
<lsl>llSetText("Monkeys\n\n\n\n\n", <1.0, 1.0, 1.0>, 1.0);//Bad
<lsl>
llSetText("Monkeys\n \n \n \n \n ", <1.0, 1.0, 1.0>, 1.0);//Good</lsl>
//  Bad:
    llSetText("Monkeys\n\n\n\n\n", <1.0, 1.0, 1.0>, 1.0);
 
// Good:
    llSetText("Monkeys\n \n \n \n \n ", <1.0, 1.0, 1.0>, 1.0);
</lsl>
|examples=
|examples=
Example of how llSetText could be included in default code to show object's name in green text:
Example of how llSetText could be included in default code to show object's name in green text:
<lsl>default
<lsl>
default
{
{
     state_entry()
     state_entry()
     {
     {
        llSay(0, "Hello, Avatar!");
    //  PUBLIC_CHANNEL has the integer value 0
        llSetText(llGetObjectName(), <0.0, 1.0, 0.0>, 1.0); // Display the object's current name in green
        llSay(PUBLIC_CHANNEL, "Hello, Avatar!");
    }


     touch_start(integer total_number)
     //  prim's name (NOT OBJECTS !!!) in green and opaque
    {
        llSetText(llGetObjectName(), <0.0, 1.0, 0.0>, (float)TRUE);
        llSay(0, "Touched.");
     }
     }
}</lsl>
}
</lsl>
By default the floating text will appear on a single line. However, the floating text can be spread over multiple lines by using a line break "\n" (read [[SplitLine]] in section 'See Also').
By default the floating text will appear on a single line. However, the floating text can be spread over multiple lines by using a line break "\n" (read [[SplitLine]] in section 'See Also').
===Color & Alpha===
===Color & Alpha===
Line 68: Line 78:
{{!}}}
{{!}}}
The x, y & z components of the vector are used to represent red, green, and blue respectively. The range is different than traditional RGB, instead of being 0 -> 255, LSL uses 0 -> 1. <1.0, 1.0, 1.0>, means "white" and <0.0, 0.0, 0.0> means "black":
The x, y & z components of the vector are used to represent red, green, and blue respectively. The range is different than traditional RGB, instead of being 0 -> 255, LSL uses 0 -> 1. <1.0, 1.0, 1.0>, means "white" and <0.0, 0.0, 0.0> means "black":
<lsl>llSetText("I am white", <1.0, 1.0, 1.0>, 1.0);//white text</lsl>
<lsl>
<lsl>llSetText("I am black", <0.0, 0.0, 0.0>, 1.0);//black text</lsl>
//  <1.0, 1.0, 1.0> as color is white
 
    llSetText("I am white", <1.0, 1.0, 1.0>, 1.0);
</lsl>
<lsl>
//  ZERO_VECTOR is <0.0, 0.0, 0.0> and as color black
 
    llSetText("I am black", ZERO_VECTOR, 1.0);
</lsl>
The 1.0 is the alpha setting. 1.0 means fully opaque, and 0.0 would be completely transparent (invisible):
The 1.0 is the alpha setting. 1.0 means fully opaque, and 0.0 would be completely transparent (invisible):
<lsl>llSetText("alpha", <0.0, 1.0, 0.0>, 0.5);//50% translucent green text</lsl>
<lsl>
    llSetText("green text with alpha 0.5", <0.0, 1.0, 0.0>, 0.5);
 
    llSetText("white text with alpha 1.0\nfully opaque", <1.0, 1.0, 1.0>, 1.0);
    llSetText("white text with alpha 1.0\nfully opaque", <1.0, 1.0, 1.0>, (float)TRUE);
 
    llSetText("invisible black text with alpha 0.0\nfully transparent", ZERO_VECTOR, 0.0);
    llSetText("invisible black text with alpha 0.0\nfully transparent", <0.0, 0.0, 0.0>, (float)FALSE);
</lsl>
===Multiple lines===
===Multiple lines===
<lsl>llSetText("I am \n on two lines!", <0.0, 1.0, 0.0>, 1.0);//two lines of green text</lsl>
<lsl>
//  two lines of green text
 
    llSetText("I am \n on two lines!", <0.0, 1.0, 0.0>, 1.0);
</lsl>
|helpers=
|helpers=
Drag this script out of inventory onto an object to erase its set text:
Drag this script out of inventory onto an object to erase its set text:
<lsl>// http://wiki.secondlife.com/wiki/llSetText
<lsl>
// http://wiki.secondlife.com/wiki/llSetText
 
default
default
{
{
     state_entry()
     state_entry()
     {
     {
         llSetText("", <1.0, 1.0, 1.0>, 1.0);
    //  black and transparent
         llSetText("", ZERO_VECTOR, (float)FALSE);
 
         llRemoveInventory(llGetScriptName());
         llRemoveInventory(llGetScriptName());
     }
     }
}</lsl>
}
</lsl>
Code to easily specify appearance of hovertext:
Code to easily specify appearance of hovertext:
<lsl>
<lsl>
vector  blue        = <0,0,1>;
vector  blue        = <0.0, 0.0, 1.0>;
vector  orange      = <1,0.5,0>;
vector  orange      = <1.0, 0.5, 0.0>;
vector  cyan        = <0,1,1>;
vector  cyan        = <0.0, 1.0, 1.0>;
vector  pink        = <1,0.5,0.76>;
vector  pink        = <1.0, 0.5, 0.76>;
vector  green      = <0,1,0>;
vector  green      = <0.0, 1.0, 0.0>;
vector  red        = <1,0,0>;
vector  red        = <1.0, 0.0, 0.0>;
vector  white      = <1,1,1>;
vector  white      = <1.0, 1.0, 1.0>;
vector  yellow      = <1,1,0.1>;
vector  yellow      = <1.0, 1.0, 0.1>;
vector  purple      = <1,0,1>;
vector  purple      = <1.0, 0.0, 1.0>;
vector  black      = <0,0,0>;
vector  black      = <0.0, 0.0, 0.0>;


string  hoverText  = "TEXT GOES HERE"; // Sets the text
string  hoverText  = "TEXT GOES HERE";
vector  hoverColor  = white; // Sets the color the text will show. Use predefined colors or any RGB color vector in float form
vector  hoverColor  = white;// set predefined color or any RGB color vector in float form
float  hoverAlpha  = 1.0; // Sets the text's transparency, 1.0 being SOLID, while 0 would be clear,
float  hoverAlpha  = 1.0; // Sets the text's transparency, 1.0 being opaque, while 0.0 would be transparent


default
default
Line 108: Line 143:
         llSetText(hoverText, hoverColor, hoverAlpha);
         llSetText(hoverText, hoverColor, hoverAlpha);
     }
     }
}</lsl>
}
</lsl>
To make hovertext under linked prims you can use this simple function:
To make hovertext under linked prims you can use this simple function:
<lsl>
<lsl>
mySetLinkText(integer linknum, string text, vector color, float alpha) {
mySetLinkText(integer linknum, string text, vector color, float alpha) {
     llSetLinkPrimitiveParamsFast(linknum,[PRIM_TEXT,text,color,alpha]);
     llSetLinkPrimitiveParamsFast(linknum, [PRIM_TEXT,text,color,alpha]);
}
}


Line 123: Line 159:
         mySetLinkText(LINK_SET, "TEST", <0,1,0>, 0.5);
         mySetLinkText(LINK_SET, "TEST", <0,1,0>, 0.5);
     }
     }
}</lsl>
}
</lsl>
|also
|also
|also_functions
|also_functions

Revision as of 09:20, 1 November 2012

Summary

Function: llSetText( string text, vector color, float alpha );

Displays text that hovers over the prim with specific color and translucency (specified with alpha).

• string text floating text to display
• vector color color in RGB <R, G, B> (<0.0, 0.0, 0.0> = black, <1.0, 1.0, 1.0> = white)
• float alpha from 0.0 (clear) to 1.0 (solid) (0.0 <= alpha <= 1.0)

Caveats

  • Do not rely on Floating Text as a storage medium; it is neither secure nor finalized.
    • Floating text has been altered in past server updates, breaking existing content; future changes may occur.
    • Even "invisible"[1] floating text is transmitted to the client.
      • It can be viewed by anyone with a client that is capable of rendering text that is supposed to be invisible.
      • The network packets that contain the text can be sniffed and the text read.
  • If more than one llSetText is called (By reset,interaction or script state) within a prim the latest call will take priority over the previous.
  • text is limited to 254 bytes, if the string is longer it will be truncated to 254 bytes, even if that means the truncation will chop a character in half.
  • An unbroken line of text of a great length may be broken automatically into two lines (one above the other).
  • Floating text can be seen through walls and other object. Be considerate of neighbors in malls and apartment buildings.
    • Visibility distance increases with prim size.
  • Removing the script or deactivating it will not remove the prim's floating text.
    • Floating text is a prim property and not dependent on a script for its continued existence.
  • To remove floating text, use the following:

<lsl> // ZERO_VECTOR has the vector value <0.0, 0.0, 0.0> // when used as a color it's black

   llSetText("", ZERO_VECTOR, 0.0);

</lsl>

  • Shift-copying does not keep the floating text prim property. If the llSetText() script is not triggered when a copy made, the copy will not have the floating text.
  • Vertical whitespace is removed from the end of the text string, so if you want vertical whitespace put any character (like a space) on the last line.
  • Multiple linebreaks with empty lines are converted to a single linebreak, so add a whitespace character on every line you want to skip:

<lsl> // Bad:

   llSetText("Monkeys\n\n\n\n\n", <1.0, 1.0, 1.0>, 1.0);

// Good:

   llSetText("Monkeys\n \n \n \n \n ", <1.0, 1.0, 1.0>, 1.0);

</lsl>

All Issues ~ Search JIRA for related Bugs

Examples

Example of how llSetText could be included in default code to show object's name in green text: <lsl> default {

   state_entry()
   {
   //  PUBLIC_CHANNEL has the integer value 0
       llSay(PUBLIC_CHANNEL, "Hello, Avatar!");
   //  prim's name (NOT OBJECTS !!!) in green and opaque
       llSetText(llGetObjectName(), <0.0, 1.0, 0.0>, (float)TRUE);
   }

} </lsl> By default the floating text will appear on a single line. However, the floating text can be spread over multiple lines by using a line break "\n" (read SplitLine in section 'See Also').

Color & Alpha

Color Code
White <1.0, 1.0, 1.0>
Grey <0.5, 0.5, 0.5>
Black <0.0, 0.0, 0.0>
Red <1.0, 0.0, 0.0>
Green <0.0, 1.0, 0.0>
Blue <0.0, 0.0, 1.0>

The x, y & z components of the vector are used to represent red, green, and blue respectively. The range is different than traditional RGB, instead of being 0 -> 255, LSL uses 0 -> 1. <1.0, 1.0, 1.0>, means "white" and <0.0, 0.0, 0.0> means "black": <lsl> // <1.0, 1.0, 1.0> as color is white

   llSetText("I am white", <1.0, 1.0, 1.0>, 1.0);

</lsl> <lsl> // ZERO_VECTOR is <0.0, 0.0, 0.0> and as color black

   llSetText("I am black", ZERO_VECTOR, 1.0);

</lsl> The 1.0 is the alpha setting. 1.0 means fully opaque, and 0.0 would be completely transparent (invisible): <lsl>

   llSetText("green text with alpha 0.5", <0.0, 1.0, 0.0>, 0.5);
   llSetText("white text with alpha 1.0\nfully opaque", <1.0, 1.0, 1.0>, 1.0);
   llSetText("white text with alpha 1.0\nfully opaque", <1.0, 1.0, 1.0>, (float)TRUE);
   llSetText("invisible black text with alpha 0.0\nfully transparent", ZERO_VECTOR, 0.0);
   llSetText("invisible black text with alpha 0.0\nfully transparent", <0.0, 0.0, 0.0>, (float)FALSE);

</lsl>

Multiple lines

<lsl> // two lines of green text

   llSetText("I am \n on two lines!", <0.0, 1.0, 0.0>, 1.0);
</lsl>

Useful Snippets

Drag this script out of inventory onto an object to erase its set text: <lsl> // http://wiki.secondlife.com/wiki/llSetText

default {

   state_entry()
   {
   //  black and transparent
       llSetText("", ZERO_VECTOR, (float)FALSE);
       llRemoveInventory(llGetScriptName());
   }

} </lsl> Code to easily specify appearance of hovertext: <lsl> vector blue = <0.0, 0.0, 1.0>; vector orange = <1.0, 0.5, 0.0>; vector cyan = <0.0, 1.0, 1.0>; vector pink = <1.0, 0.5, 0.76>; vector green = <0.0, 1.0, 0.0>; vector red = <1.0, 0.0, 0.0>; vector white = <1.0, 1.0, 1.0>; vector yellow = <1.0, 1.0, 0.1>; vector purple = <1.0, 0.0, 1.0>; vector black = <0.0, 0.0, 0.0>;

string hoverText = "TEXT GOES HERE"; vector hoverColor = white;// set predefined color or any RGB color vector in float form float hoverAlpha = 1.0; // Sets the text's transparency, 1.0 being opaque, while 0.0 would be transparent

default {

   state_entry()
   {
       llSetText(hoverText, hoverColor, hoverAlpha);
   }

} </lsl> To make hovertext under linked prims you can use this simple function: <lsl> mySetLinkText(integer linknum, string text, vector color, float alpha) {

   llSetLinkPrimitiveParamsFast(linknum, [PRIM_TEXT,text,color,alpha]);

}

// For example:

default {

   touch_start(integer total_number)
   {
       mySetLinkText(LINK_SET, "TEST", <0,1,0>, 0.5);
   }

} </lsl>

Notes

To actually display text on a prim, see XyzzyText, or consider using parcel prim Media options (useful only if you have control over the land's media settings.)


The function displays text that hover over the prim's center, the prim position. The height over the center is proportional to the prim's Z-dimension exclusively

  • It doesn't matter how the prim is rotated, so if Z is smaller than X and Y the text may be seen on the prim

See Also

Constants

•  PRIM_TEXT

Articles

•  Limits SL limits and constrictions
•  Color in LSL
•  Translucent Color
•  Examples: SplitLine Insert 'new line' escape codes at certain positions of a string
•  Useful snippet: llGetObjectPermMask Label an object with text and newlines to give away or sell

Deep Notes

All Issues

~ Search JIRA for related Issues
   llSetText is not working with special characters.

Footnotes

  1. ^ Floating text with an alpha set to 0.0 is rendered "invisible"

Signature

function void llSetText( string text, vector color, float alpha );