Difference between revisions of "LlSetText"

From Second Life Wiki
Jump to navigation Jump to search
m
(bad style, bad information)
Line 1: Line 1:
AKA "floating text" in the popular vernacular. This creates text that floats / hovers above the prim.
To actually display text on a prim, see [[XyzzyText]], or consider using parcel prim [[:Category:LSL_Media|Media]] options (useful only you have control over the land's media settings.)
{{LSL Function/color|color}} {{LSL Function/alpha|alpha}}{{LSL_Function
{{LSL Function/color|color}} {{LSL Function/alpha|alpha}}{{LSL_Function
|func_id=152
|func_id=152
Line 10: Line 5:
|func=llSetText
|func=llSetText
|sort=SetText
|sort=SetText
|p1_type=string|p1_name=text|p1_desc=text to display between the quotes
|p1_type=string|p1_name=text|p1_desc=text to display
|p2_type=vector|p2_name=color
|p2_type=vector|p2_name=color
|p3_type=float|p3_name=alpha
|p3_type=float|p3_name=alpha
|func_desc=Displays '''text''' over a prim with specific '''color''' and transparency (specified with '''alpha''').
|func_desc=Displays '''text''' that hovers over the prim with specific '''color''' and translucency (specified with '''alpha''').  
|return_text
|return_text
|spec=
|spec=
|caveats=
|caveats=
*A script calling llSetText cannot know if it is or is not changing the floating text, since there is no mirror [[llGetText]] function;
*'''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.
*Nor, for the same lack of the "missing" [[llGetText]] function, can a script know what text is hovering about a prim;
*Floating text can be seen through walls and other object. Be considerate of neighbors in malls and apartment buildings.
*The limit on the character length of floating text is 255 characters;
*There is no way for a script to determine the prims current floating text or detect when it is changed.
*Floating text will go right through walls or any other object. Be considerate of neighbours in malls and apartment buildings.
**There is no [[llGetText]] function or [[CHANGED_TEXT]] [[changed]] event flag.
*Removing the script or deactivating it will not remove the prims floating text.
**Floating text is a prim property and not dependent or changed to a script to continue to exist.
*To remove floating text, use the following:
<lsl>llSetText("", <1.0, 1.0, 1.0>, 1.0);</lsl>
*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:
<lsl>llSetText("Monkeys\n\n\n\n\n", <1.0, 1.0, 1.0>, 1.0);//Bad
llSetText("Monkeys\n\n\n\n\n ", <1.0, 1.0, 1.0>, 1.0);//Good</lsl>
|examples=
Example of how llSetText could be included in default code to show object's name in green text:
<lsl>default
{
    state_entry()
    {
        llSay(0, "Hello, Avatar!");
        llSetText(llGetObjectName(), <0.0, 1.0, 0.0>, 1.0); // Display the object's current name in green
    }


 
    touch_start(integer total_number)
== Removing Floating Text ==
    {
Floating text is a property of a prim and not a script. For that reason, the text will remain if the script is deactivated or even removed.
        llSay(0, "Touched.");
 
    }
To remove floating text, you don't actually remove it, but rather swap in an empty string like this:
}</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').
llSetText("", <1.0, 1.0, 1.0>, 1.0);
===Color & Alpha===
</lsl>
{{{!}} class="sortable" {{Prettytable|style=float:right; margin-top:0;}}
 
{{!}}- {{Hl2}}
Here is a complete script to erase the floating text of an object. You can just make the script in inventory, replace its contents with the script text below, and drag this script into the contents of the object:
! Color
 
! Code
<lsl>
{{!}}- style="background:white"
default {
{{!}}White
     state_entry(){
{{!}}<1.0, 1.0, 1.0>
         llSetText("", <0.0, 0.0, 0.0>, 0.0);
{{!}}- style="background:grey"
{{!}}Grey
{{!}}<0.5, 0.5, 0.5>
{{!}}- style="background:black; color:white;"
{{!}}{{!}}Black
{{!}}<0.0, 0.0, 0.0>
{{!}}- style="background:red; color:white;"
{{!}}Red
{{!}}<1.0, 0.0, 0.0>
{{!}}- style="background:green; color:white;"
{{!}}Green
{{!}}<0.0, 1.0, 0.0>
{{!}}- style="background:blue; color:white;"
{{!}}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 then 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 on", <1.0, 1.0, 1.0>, 1.0);//white text</lsl>
<lsl>llSetText("I am off", <0.0, 0.0, 0.0>, 1.0);//black text</lsl>
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>
===Multiple lines===
<lsl>llSetText("I am \n on two lines!", <0.0, 1.0, 0.0>, 1.0);//two lines of green text</lsl>
|helpers=
Drag this script out of inventory onto an object to erase its set text:
<lsl>// http://wiki.secondlife.com/wiki/llSetText
default
{
     state_entry()
    {
         llSetText("", <1.0, 1.0, 1.0>, 1.0);
         llRemoveInventory(llGetScriptName());
         llRemoveInventory(llGetScriptName());
     }
     }
}
}</lsl>
</lsl>
 
 
 
== Font face and size ==
 
Apart from colour, we don't have a lot of control over how floating text will appear.
 
You cannot, for instance, change the font, or the size of the font.
 
Nor can you align it to right or left. It will always be centred horizontally above the prim.
 
 
== Height ==
 
Floating text floats straight up on the Z-axis (the world's, not the prim's) from the centre of the prim (that contained the script that called it) to be above the prim at a height equivalent to half the prim's Z scale (plus a bit more.)
 
You can push floating text up higher above the prim by doing something like this:
 
llSetText("Monkeys\n\n\n\n\n ", <1.0, 1.0, 1.0>, 1.0);
 
The \n 's stand for newlines, so in the above example, the floating text will be 5 lines higher than normal above the prim.
 
Note the space after the last \n : pure vertical space is auto-trimmed from the end of a floating text string. You trick the system into leaving it alone by adding that one space.
 
 
== Wrapping ==
By default, any floating text will appear on a single line. Sometimes these single lines of floating text can be absurdly long.
 
However, the floating text can be spread over multiple lines by inserting line breaks ("\n").
 
You can do this manually, or by using functions such as [[SplitLine]] (which requires separators to be in the text), or [[WrapText]] (which does not require separators in the text and allows you to specify the line-length you feel best.)
 
 
|examples=
 
'''Example: Manual multiple line'''
<lsl>
llSetText("I am \n on two lines!", <0.0, 1.0, 0.0>, 1.0);
</lsl>
 
 
'''Example: Including llSetText in default code''' to show object's name in green text:
<lsl>
default{
    state_entry() {
          llSay(0, "Hello, Avatar!");
          llSetText(llGetObjectName(), <0.0, 1.0, 0.0>, 1.0); // Display object's name in green
    }
    touch_start(integer total_number){
          llSay(0, "Touched.");
    }
}
</lsl>
 
 
'''Example: Use prim name as the text, wrapped to display on several lines'''
 
<lsl>
 
string WrapText(string pcText, integer piWidth) {
    list    laLines  = [];
    integer  liIndex;
    integer  liKeep;  // Specifies if we keep the char pointed at or not
    integer  liLen    = llStringLength(pcText);
    list    llSearch = [" ", "\n"];
   
    while (liLen > 0) {
        liIndex = piWidth;
        if (!(liKeep = (liLen <= piWidth))) {
            while ((liIndex >= 0) && (-1 == llListFindList(llSearch, (list)llGetSubString(pcText, liIndex, liIndex))))
                --liIndex;
            if (liIndex <= 0) {
                liIndex = piWidth;
                liKeep = 1;
            }
        }
        laLines += llGetSubString(pcText, 0, liIndex - 1);
        pcText = llDeleteSubString(pcText, 0, liIndex - liKeep);
        liLen -= (1 + liIndex - liKeep);
    }
    return llDumpList2String(laLines,"\n");
}
 
 
default {
    state_entry() {
          string tmp = WrapText(llGetObjectName(),25);
          llSetText(tmp, <1.0, 1.0, 1.0>, 1.0); // Display object's name in solid white
    }
}
</lsl>
 
 
'''Example: Colours'''
 
<lsl>
vector white = <1.0, 1.0, 1.0>;
vector red = <1.0, 0.0, 0.0>;
vector green = <0.0, 1.0, 0.0>;
vector blue = <0.0, 0.0, 1.0>;
vector grey = <0.5, 0.5, 0.5>;
vector black = <0.0, 0.0, 0.0>;
</lsl>
<1.0, 1.0, 1.0> represents the values for red, green, and blue.
<1.0, 1.0, 1.0>, means "white" and <0.0, 0.0, 0.0> means "black":
<lsl>
llSetText("I am on", <1.0, 1.0, 1.0>, 1.0);
</lsl>
<lsl>
llSetText("I am off", <0.0, 0.0, 0.0>, 1.0);
</lsl>
 
'''Example: Alpha (transparency)'''
 
The 1.0 is the alpha setting. 1.0 means fully opaque (aka solid), and 0.0 would be completely transparent (invisible):
<lsl>
llSetText("alpha", <0.0, 1.0, 0.0>, 0.5);
</lsl>
 
'''Example: Computing the floating text'''
 
You can include functions (that return strings) in the text to be displayed:
 
<lsl>
llSetText("Hello, and welcome to " + llGetRegionName(), <1.0,1.0,1.0>, 1);
</lsl>
 
 
|also
|also
|also_functions
|also_functions
Line 175: Line 86:
{{LSL DefineRow||[[:Category:LSL Examples|Examples]]: [[SplitLine]]|Insert 'new line' escape codes at certain positions of a string}}
{{LSL DefineRow||[[:Category:LSL Examples|Examples]]: [[SplitLine]]|Insert 'new line' escape codes at certain positions of a string}}
{{LSL DefineRow||Useful snippet: [[llGetObjectPermMask]]|Label an object with text and newlines to give away or sell}}
{{LSL DefineRow||Useful snippet: [[llGetObjectPermMask]]|Label an object with text and newlines to give away or sell}}
|notes=To actually display text on a prim, see [[XyzzyText]], or consider using parcel prim [[:Category:LSL_Media|Media]] options (useful only you have control over the land's media settings.)
|cat1=Effects
|cat1=Effects
|cat2=Prim
|cat2=Prim
|cat3=Text
|cat3
|cat4
|cat4
}}
}}

Revision as of 22:35, 11 July 2008

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 – 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

  • 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.
  • Floating text can be seen through walls and other object. Be considerate of neighbors in malls and apartment buildings.
  • There is no way for a script to determine the prims current floating text or detect when it is changed.
  • Removing the script or deactivating it will not remove the prims floating text.
    • Floating text is a prim property and not dependent or changed to a script to continue to exist.
  • To remove floating text, use the following:

<lsl>llSetText("", <1.0, 1.0, 1.0>, 1.0);</lsl>

  • 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:

<lsl>llSetText("Monkeys\n\n\n\n\n", <1.0, 1.0, 1.0>, 1.0);//Bad llSetText("Monkeys\n\n\n\n\n ", <1.0, 1.0, 1.0>, 1.0);//Good</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()
   {
        llSay(0, "Hello, Avatar!");
        llSetText(llGetObjectName(), <0.0, 1.0, 0.0>, 1.0); // Display the object's current name in green
   }

   touch_start(integer total_number)
   {
        llSay(0, "Touched.");
   }

}</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 then 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 on", <1.0, 1.0, 1.0>, 1.0);//white text</lsl> <lsl>llSetText("I am off", <0.0, 0.0, 0.0>, 1.0);//black text</lsl> 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>

Multiple lines

<lsl>llSetText("I am \n on two lines!", <0.0, 1.0, 0.0>, 1.0);//two lines of green text</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()
   {
       llSetText("", <1.0, 1.0, 1.0>, 1.0);
       llRemoveInventory(llGetScriptName());
   }

}</lsl>

Notes

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

See Also

Articles

•  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

Search JIRA for related Issues

Signature

function void llSetText( string text, vector color, float alpha );
Retrieved from "https://wiki.secondlife.com/w/index.php?title=LlSetText&oldid=77913"