Difference between revisions of "LlDialog"

From Second Life Wiki
Jump to: navigation, search
Line 4: Line 4:
 
|p3_type=list|p3_name=buttons|p3_desc=button labels
 
|p3_type=list|p3_name=buttons|p3_desc=button labels
 
|p4_type=integer|p4_name=chat_channel|p4_desc
 
|p4_type=integer|p4_name=chat_channel|p4_desc
|func_desc=Shows a dialog box on the '''avatar''' screen with '''message''' and '''buttons'''.
+
|func_desc=Shows a blue dialog box in the upper right corner of the '''avatar's''' screen with a '''message''' and choice '''buttons''', as well as an ignore button.
 
|func_footnote=When a button is pressed, the '''avatar''' chats the text of the button label on '''chat_channel'''.<br/>The position of the chat is where the prim was when the dialog button is pressed.
 
|func_footnote=When a button is pressed, the '''avatar''' chats the text of the button label on '''chat_channel'''.<br/>The position of the chat is where the prim was when the dialog button is pressed.
 
|spec
 
|spec
Line 15: Line 15:
 
**This limitation affects attachments too if the wearer moves more than 20 meters from where the listener is located.
 
**This limitation affects attachments too if the wearer moves more than 20 meters from where the listener is located.
  
===message limits===
+
===Limits on the message displayed on the menu===
*If it exceeds 8 lines a scroll bar will appear.
+
*This message must be less than 512 bytes and not be empty. If it is empty, llDialog will shout "llDialog: must supply a message" on the [[DEBUG_CHANNEL]]. If it is over 512 bytes, it shouts (again on the debug channel): "llDialog: message too long, must be less than 512 characters";
*'''message''' must be less than 512 bytes and not empty. Otherwise it will shout an error on [[DEBUG_CHANNEL]].
+
*In both instances, the dialog menu will not be created for the user.
 +
 
  
 
===buttons limits===
 
===buttons limits===
Line 112: Line 113:
 
     ["Yes", "No", "0", "1"], channel);</lsl>
 
     ["Yes", "No", "0", "1"], channel);</lsl>
 
Negative channels are popular for script communications because the client is unable to chat directly on those channels ("/-xxxx message" won't chat "message" on channel "-xxxx", it will chat "/-xxxx message" on channel zero). The only way to do so prior to [[llTextBox]] was to use [[llDialog]] which was limited to 24 bytes.
 
Negative channels are popular for script communications because the client is unable to chat directly on those channels ("/-xxxx message" won't chat "message" on channel "-xxxx", it will chat "/-xxxx message" on channel zero). The only way to do so prior to [[llTextBox]] was to use [[llDialog]] which was limited to 24 bytes.
 +
 +
 +
You can ensure that all of your scripted objects have a unique chat channel with this small function:
 +
 +
<lsl>
 +
integer dialog_channel; // top of script in variables
 +
 +
integer channel() { // top of script in functions
 +
    return (integer)("0x"+llGetSubString((string)llGetKey(),-4,-1));
 +
}
 +
 +
dialog_channel = channel(); // somewhere in actual script execution, such as state_entry()
 +
</lsl>
 +
 +
 +
'''The Menu Appearance'''
 +
 +
If message displayed on the menu exceeds 8 lines, a vertical scroll bar will appear on the menu.
 +
 +
The message text can be formatted somewhat using "\n" (for newline) and "\t" (for tab). You can do nothing though to influence the font face, size or weight.
 +
 +
There is no way to change the actual size of the blue menu, nor change its colour.
 +
 +
 +
 
|also_events=
 
|also_events=
 
{{LSL DefineRow||[[listen]]|}}
 
{{LSL DefineRow||[[listen]]|}}

Revision as of 20:00, 14 July 2008

Summary

Function: llDialog( key avatar, string message, list buttons, integer chat_channel );

Shows a blue dialog box in the upper right corner of the avatar's screen with a message and choice buttons, as well as an ignore button.

• key avatar avatar UUID
• string message message to be displayed
• list buttons button labels
• integer chat_channel output chat channel, any integer value

When a button is pressed, the avatar chats the text of the button label on chat_channel.
The position of the chat is where the prim was when the dialog button is pressed.

Button Order
9   10 11
6 7 8  
3 4 5
0 1 2
Channel Constant Description
DEBUG_CHANNEL 0x7FFFFFFF Chat channel reserved for script debugging and error messages, broadcasts to all nearby users.
PUBLIC_CHANNEL 0x0 Chat channel that broadcasts to all nearby users. This channel is sometimes referred to as: open chat, local chat and public chat.

Caveats

  • This function causes the script to sleep for 1.0 seconds.
  • Messages sent on channel zero[1] and DEBUG_CHANNEL are throttled to a rate of <200/10sec, per region, per owner/user.
    • Once the rate is exceeded, all following messages on channel zero or DEBUG_CHANNEL will be dropped until the send rate is again below 200/10sec for the previous 10 sec. Dropped messages, despite being dropped still count against the limit.
  • There is no way by script to kill a dialog box.
  • There is no way for the script to detect if the user clicked the small "ignore" button (no chat is generated as a result of pressing this button).
  • There is no way to distinguish the input from a dialog box and regular chat made by the same user.
    • It is important to expect that the response may not be one of the buttons.
  • If the listening prim is out of the 20 meter range of the sending prim when a button is pressed, it will not be able to hear the response.
    • This limitation affects attachments too if the wearer moves more than 20 meters from where the listener is located.

Limits on the message displayed on the menu

  • This message must be less than 512 bytes and not be empty. If it is empty, llDialog will shout "llDialog: must supply a message" on the DEBUG_CHANNEL. If it is over 512 bytes, it shouts (again on the debug channel): "llDialog: message too long, must be less than 512 characters";
  • In both instances, the dialog menu will not be created for the user.


buttons limits

  • If buttons is an empty list, it will default to as if it were ["OK"]
  • An error will be shouted on DEBUG_CHANNEL, if...
    • there are more than 12 buttons.
    • any list item is not a string.
    • any list item string length (in bytes) is zero or greater than 24.
All Issues ~ Search JIRA for related Bugs

Examples

<lsl>integer channel = 1000;

default {

   state_entry()
   {
       llListen(channel,"", "","");
   }
   touch_start(integer count)
   {
       llDialog(llDetectedKey(0), "This is a test dialog.\n\nPlease choose one of the below options.",
                ["Yes", "No", "0", "1"], channel);
   }
   
   listen(integer chan, string name, key id, string mes)
   {
       if(id == llGetOwnerKey(id))//won't listen to objects unless they aren't in the region.
           llSay(0,name + " (" + (string)llGetObjectDetails(id, (list)OBJECT_POS) + ") chose option " + mes);
   }
}</lsl>

Useful Snippets

<lsl>//Compact function to put buttons in "correct" human-readable order integer channel;

list order_buttons(list buttons) {

   return llList2List(buttons, -3, -1) + llList2List(buttons, -6, -4)
       + llList2List(buttons, -9, -7) + llList2List(buttons, -12, -10);

}

default {

   state_entry()
   {   // Create random channel within range [-1000000000,-2000000000]

channel = (integer)(llFrand(-1000000000.0) - 1000000000.0);

llListen(channel,"", "","");

   }
   touch_start(integer total_number)
   {
       llDialog(llDetectedKey(0),"\nPlease choose an option:\n",

order_buttons(["1", "2", "3", "4", "5", "6", "7", "8", "9", "10"]),channel);

   }
   listen(integer _chan, string _name, key _id, string _option)
   {
       llSay(0, _name + " chose option " + _option);
   }

}</lsl>

Notes

It is a good idea to use a very negative channel (if never more negative than the most negative 32-bit integer that is -2,147,483,648), e.g., <lsl>// Create random channel within range [-1000000000,-2000000000] integer channel = (integer)(llFrand(-1000000000.0) - 1000000000.0);

llDialog(llDetectedKey(0), "Please choose one of the below options:",

   ["Yes", "No", "0", "1"], channel);</lsl>

Negative channels are popular for script communications because the client is unable to chat directly on those channels ("/-xxxx message" won't chat "message" on channel "-xxxx", it will chat "/-xxxx message" on channel zero). The only way to do so prior to llTextBox was to use llDialog which was limited to 24 bytes.


You can ensure that all of your scripted objects have a unique chat channel with this small function:

<lsl> integer dialog_channel; // top of script in variables

integer channel() { // top of script in functions

   return (integer)("0x"+llGetSubString((string)llGetKey(),-4,-1));

}

dialog_channel = channel(); // somewhere in actual script execution, such as state_entry() </lsl>


The Menu Appearance

If message displayed on the menu exceeds 8 lines, a vertical scroll bar will appear on the menu.

The message text can be formatted somewhat using "\n" (for newline) and "\t" (for tab). You can do nothing though to influence the font face, size or weight.

There is no way to change the actual size of the blue menu, nor change its colour.

See Also

Events

•  listen

Functions

•  llListen
•  llTextBox
•  llRegionSay
•  llWhisper Sends chat limited to 10 meters
•  llSay Sends chat limited to 20 meters
•  llShout Sends chat limited to 100 meters
•  llInstantMessage
•  llOwnerSay Sends chat to the owner only

Deep Notes

Search JIRA for related Issues

Footnotes

  1. ^ Channel zero is also known as: PUBLIC_CHANNEL, open chat, local chat and public chat

Signature

function void llDialog( key avatar, string message, list buttons, integer chat_channel );