MultiUser Dialog Handler

Introduction

I found that i was constantly rewriting a pile of dialog handling functions in my scrips so i decided to write a single dialog handler script. It needed to have the following features;

• Support multiple simultaneous menus from different users, scripts and prims.
• Support fixed top buttons that will persist on lists.
• Support fixed bottom buttons with include Back and Exit buttons.
• Handle item lists > 12 and automatically insert << and >> buttons to scroll through the lists.
• Handle timeouts and communicate timeout back to calling script.
• Handles truncation of the buttons and text to stop errors in llDialog

Using The Script

Calling a Simple Menu

In the script that is calling the menu I use a function something like this.

// Link Commands
integer     LINK_MENU_DISPLAY = 300;
integer     LINK_MENU_RETURN = 320;
integer     LINK_MENU_TIMEOUT = 330;


DisplayMenu(key id)
{   // Menu Functions
    string  menuDescripter = "mymenu";  //An identifier to show what menu called the script. I often include the script name plus menu name.
    string  menuNavigate = "FALSE";      //Navigation buttons not displayed
    string  menuText = "This is the menu text that will be displayed.";  // The text will be trimmed to 510 characters
    string  menuButtons =  "TopLeft~Top~TopRight~Left~Center~Right~BottomLeft~Bottom~BottomRight";   // The buttons, each button separated by a '~'.
        
    llMessageLinked(LINK_THIS, LINK_MENU_DISPLAY, menuDescripter+"|"+menuNavigate+"|"+menuText+"|"+ menuButtons, id);
}

This will display a menu that looks something like

This is the menu text that will be displayed.

TopLeft	Top	TopRight
Left	Center	Right
BottomLeft	Bottom	BottomRight

Calling a Simple Menu with Auto-Navigation Buttons

In this case we now add navigation buttons to the bottom of the script. Back and Exit buttons are added to the bottom and if necessary >> and << buttons. In the script that is calling the menu I use a function something like this.

// Link Commands
integer     LINK_MENU_DISPLAY = 300;
integer     LINK_MENU_RETURN = 320;
integer     LINK_MENU_TIMEOUT = 330;


DisplayMenu(key id)
{   // Menu Functions
    string  menuDescripter = "mymenu";  //An identifier to show what menu called the script. I often include the script name plus menu name.
    string  menuNavigate = "TRUE";      //The display of the bottom navigation buttons is set to TRUE
    string  menuText = "This is the menu text that will be displayed.";  // The text will be trimmed to 510 characters
    string  menuButtons =  "Owner~Group~All";                            // The buttons, each button separated by a '~'.  Buttons will be trimmed to 24 characters
        
    llMessageLinked(LINK_THIS, LINK_MENU_DISPLAY, menuDescripter+"|"+menuNavigate+"|"+menuText+"|"+ menuButtons, id);
}

This will display a menu that looks something like this.

This is the menu text that will be displayed.

Owner	Group	All
	Back	Exit

Calling a Complex Menu

In the following case we will have 10 buttons that are going to be displayed. Because we will also display the bottom 3 buttons this will be spanned across 2 menus. We will also include 2 fixed buttons that always display at the top of the menu, PLUS each button has a unique descriptor that is displayed. Here is the menu call.

// Link Commands
integer     LINK_MENU_DISPLAY = 300;
integer     LINK_MENU_RETURN = 320;
integer     LINK_MENU_TIMEOUT = 330;


DisplayMenu(key id)
{   // Menu Functions
    string  menuDescripter = "mymenu"
    string  menuNavigate = "TRUE";
    string  menuText = "Main text displayed.~text1~text2~text3~text4~text5~text6~text7~text8~text9~text10"; 
    string  menuButtons =  "B1~B2~B3~B4~B5~B6~B7~B8~B9~B10";                            
    string  menuFixedButtons = "FIXED1~FIXED2"
        
    llMessageLinked(LINK_THIS, LINK_MENU_DISPLAY, menuDescripter+"|"+menuNavigate+"|"+menuText+"|"+ menuButtons+"|"+menuFixedButtons, id);
}

This will display the following 2 menus

Menu1

Main text displayed.
item1
item2
item3
item4
item5
item6
item7

FIXED1	FIXED2	B1
B2	B3	B4
B5	B6	B7
	Back	>>

Menu2 (on clicking the >> button)

Main text displayed.
item8
item9
item10

FIXED1	FIXED2	B8
B9	B10
<<	Back	Exit

Parsing the returning Menu information

Note that if the user clicks on the << or >> buttons the calling script WILL NOT see any response. The correct menu is displayed. The calling script only receives a response when one of the buttons or Back/Exit are clicked. Clicking on a space button will cause the menu to redisplay.

The script that expects the response back from the menu has the following

// Link Commands
integer     LINK_MENU_DISPLAY = 300;
integer     LINK_MENU_RETURN = 320;
integer     LINK_MENU_TIMEOUT = 330;


default
{
    link_message(integer intSenderNum, integer num, string message, key id) 
    { 
        if (num == LINK_MENU_RETURN)
        {
            list    returnMenu = llParseString2List(message, ["|"], []);
            string  menuDescriptor = llList2String(returnMenu,0);        // The idenfifying descriptor.  I sometimes use the name of the script plus menu and parent menu name    
            
            if (menuDescriptor == "mymenu")
            {    // Is this a response to "mymenu" from the dialog script?
                 string  item = llList2String(returnMenu,1);             // The actual button pushed

                 // id == the key of the menu user.
                 // The button pressed in the menu is 'item', so now do something with it
            }
         }
         else if (num == LINK_MENU_TIMEOUT)
         {
             if (message == "mymenu")
             {
                // We received a timeout (don't worry the listens are all dealt with) so you might want to IM the menu user.
             }
         }
    }
}

The Script

// ********************************************************************
//
// Menu Display Script 
//
// Menu command format
// string = menuidentifier | display navigate? TRUE/FALSE | menuMaintitle~subtitle1~subtitle2~subtitle3 | button1~button2~button3 {| fixedbutton1~fixedbutton2~fixedbutton3  optional}
// key = menuuser key
//
// Return is in the format
// "menuidentifier | item"
//
// menusDescription [menuchannel, key, menu & parent, return link, nav?,  titles, buttons, fixed buttons]
// menusActive      [menuchannel, menuhandle, time, page] 
//
// by SimonT Quinnell
//
// CHANGES
// 2010/10/14 - Timeout message now gets sent to the prim that called the menu, not LINK_THIS.  Also includes menuidentifier
// 2010/11/29 - Fixed Bug in RemoveUser function.  Thanks for Virtouse Lilienthal for pointing it out.
// 2010/11/29 - Tidied up a little and removed functions NewMenu and RemoveUser that are only called once
// 2014/04/28 - Clarified licence
//
// NOTE: This script is licenced using the Creative Commons Attribution-Share Alike 3.0 license
//
// ********************************************************************


// ********************************************************************
// CONSTANTS
// ********************************************************************

// Link Commands
integer     LINK_MENU_DISPLAY = 300;
integer     LINK_MENU_CLOSE = 310; 
integer     LINK_MENU_RETURN = 320;
integer     LINK_MENU_TIMEOUT = 330;

// Main Menu Details
string      BACK = "<<";
string      FOWARD = ">>";
list        MENU_NAVIGATE_BUTTONS = [ " ", "Back", "Exit"];
float       MENU_TIMEOUT_CHECK = 10.0;
integer     MENU_TIMEOUT = 120;
integer     MAX_TEXT = 510;


integer     STRIDE_DESCRIPTION = 8;
integer     STRIDE_ACTIVE = 4;
integer     DEBUG = FALSE;

// ********************************************************************
// Variables
// ********************************************************************

list    menusDescription;
list    menusActive;


// ********************************************************************
// Functions - General
// ********************************************************************
                   
debug(string debug)
{
    if (DEBUG) llSay(DEBUG_CHANNEL,"DEBUG:"+llGetScriptName()+":"+debug+" : Free("+(string)llGetFreeMemory()+")");
}  
                
               
integer string2Bool (string test)
{
    if (test == "TRUE") return TRUE;
    else return FALSE;
}

// ********************************************************************
// Functions - Menu Helpers
// ********************************************************************

integer NewChannel()
{    // generates unique channel number
    integer channel;

    do channel = -(llRound(llFrand(999999)) + 99999);
    while (~llListFindList(menusDescription, [channel]));

    return channel;    
}


string  CheckTitleLength(string title)
{
    if (llStringLength(title) > MAX_TEXT) title = llGetSubString(title, 0, MAX_TEXT-1);
    
    return title;
}


list FillMenu(list buttons)
{   //adds empty buttons until the list length is multiple of 3, to max of 12
    integer i;
    list    listButtons;
    
    for(i=0;i<llGetListLength(buttons);i++)
    {
        string name = llList2String(buttons,i);
        if (llStringLength(name) > 24) name = llGetSubString(name, 0, 23);
        listButtons = listButtons + [name];
    }
    
    while (llGetListLength(listButtons) != 3 && llGetListLength(listButtons) != 6 && llGetListLength(listButtons) != 9 && llGetListLength(listButtons) < 12)
    {
        listButtons = listButtons + [" "];
    }
    
    buttons = llList2List(listButtons, 9, 11);
    buttons = buttons + llList2List(listButtons, 6, 8);
    buttons = buttons + llList2List(listButtons, 3, 5);    
    buttons = buttons + llList2List(listButtons, 0, 2); 
    
    return buttons;
}

RemoveMenu(integer channel, integer echo)
{
    integer index = llListFindList(menusDescription, [channel]);

    if (index != -1)
    {
        key     menuId = llList2Key(menusDescription, index+1);
        string  menuDetails = llList2String(menusDescription, index+2);
        integer menuLink = llList2Integer(menusDescription, index+3);
        menusDescription = llDeleteSubList(menusDescription, index, index + STRIDE_DESCRIPTION - 1);
        RemoveListen(channel);

        if (echo) llMessageLinked(menuLink, LINK_MENU_TIMEOUT, menuDetails, menuId);
    }
}

RemoveListen(integer channel)
{
    integer index = llListFindList(menusActive, [channel]);
    if (index != -1)
    {    
        llListenRemove(llList2Integer(menusActive, index + 1));
        menusActive = llDeleteSubList(menusActive, index, index + STRIDE_ACTIVE - 1);
    }
}

// ********************************************************************
// Functions - Menu Main
// ********************************************************************

DisplayMenu(key id, integer channel, integer page)
{
    string  menuTitle;
    list    menuSubTitles;
    list    menuButtonsAll;
    list    menuButtons;   
    list    menuNavigateButtons;
    list    menuFixedButtons;

    integer max = 12;

    // Populate values
    integer index = llListFindList(menusDescription, [channel]);
    menuButtonsAll = llParseString2List(llList2String(menusDescription, index+6), ["~"], []);
    if (llList2String(menusDescription, index+7) != "") menuFixedButtons = llParseString2List(llList2String(menusDescription, index+7), ["~"], []);

    // Set up the menu buttons
    if (llList2Integer(menusDescription, index+4)) menuNavigateButtons= MENU_NAVIGATE_BUTTONS;
    else if (llGetListLength(menuButtonsAll) > (max-llGetListLength(menuFixedButtons))) menuNavigateButtons = [" ", " ", " "];
    
    // FIXME: add sanity check for menu page
    
    max = max - llGetListLength(menuFixedButtons) - llGetListLength(menuNavigateButtons);
    integer     start = page*max;
    integer     stop = (page+1)*max - 1;
    menuButtons = FillMenu(menuFixedButtons + llList2List(menuButtonsAll, start, stop));

    // Generate the title
    list tempTitle = llParseString2List(llList2String(menusDescription, index+5), ["~"], []);
    menuTitle = llList2String(tempTitle,0);
    if (llGetListLength(tempTitle) > 1) menuSubTitles = llList2List(tempTitle, 1, -1);
    if (llGetListLength(menuSubTitles) > 0)
    {
        integer i;
        for(i=start;i<(stop+1);++i)
        {
            if (llList2String(menuSubTitles, i) != "") menuTitle += "\n"+llList2String(menuSubTitles, i);
        }
    }
    menuTitle = CheckTitleLength(menuTitle);
    
    // Add navigate buttons if necessary
    if (page > 0) menuNavigateButtons = llListReplaceList(menuNavigateButtons, [BACK], 0, 0);
    if (llGetListLength(menuButtonsAll) > (page+1)*max) menuNavigateButtons = llListReplaceList(menuNavigateButtons, [FOWARD], 2, 2); 
    
    // Set up listen and add the row details
    integer menuHandle = llListen(channel, "", id, "");
    menusActive = [channel, menuHandle, llGetUnixTime(), page] + menusActive;

    llSetTimerEvent(MENU_TIMEOUT_CHECK);

    // Display menu
    llDialog(id, menuTitle, menuNavigateButtons + menuButtons, channel);
}
    

// ********************************************************************
// Event Handlers
// ********************************************************************  

default
{
    listen(integer channel, string name, key id, string message)
    {
        if (message == BACK) 
        { 
            integer index = llListFindList(menusActive, [channel]);
            integer page = llList2Integer(menusActive, index+3)-1;
            RemoveListen(channel);            
            DisplayMenu(id, channel, page);
        }
        else if (message == FOWARD)
        { 
            integer index = llListFindList(menusActive, [channel]);
            integer page = llList2Integer(menusActive, index+3)+1;
            RemoveListen(channel);
            DisplayMenu(id, channel, page);
        }
        else if (message == " ")
        { 
            integer index = llListFindList(menusActive, [channel]);
            integer page = llList2Integer(menusActive, index+3);
            RemoveListen(channel);
            DisplayMenu(id, channel, page);
        }
        else 
        {
            integer index = llListFindList(menusDescription, [channel]);
            llMessageLinked(llList2Integer(menusDescription, index+3), LINK_MENU_RETURN, llList2String(menusDescription, index+2)+"|"+message, id);
            RemoveMenu(channel, FALSE);
        }
    }
    
    link_message(integer senderNum, integer num, string message, key id) 
    {
        if (num == LINK_MENU_DISPLAY)
        {   // Setup New Menu
            list    temp = llParseString2List(message, ["|"], []);
            integer channel = NewChannel();
        
            if (llGetListLength(temp) > 2)
            {
                menusDescription = [channel, id, llList2String(temp, 0), senderNum,  string2Bool(llList2String(temp, 1)), llList2String(temp, 2), llList2String(temp, 3), llList2String(temp, 4)] + menusDescription;

                DisplayMenu(id, channel, 0);
            }
            else llSay (DEBUG_CHANNEL, "ERROR in "+llGetScriptName()+": Dialog Script. Incorrect menu format");
        }
        else if (num == LINK_MENU_CLOSE)
        {    // Will remove all menus that have the user id.
             integer index_id = llListFindList(menusDescription, [id]);
    
             while (~index_id) 
             {
                 integer channel = llList2Integer(menusDescription, index_id-1);
                 RemoveMenu(channel, FALSE);
        
                 // Check for another menu by same user
                 index_id = llListFindList(menusDescription, [id]);
             }
        }
    }
    
    timer()
    {   // Check through timers and close if necessary
        integer i;
        list toRemove;
        integer currentTime = llGetUnixTime();
        integer length = llGetListLength(menusActive);   
    
        for(i=0;i<length;i+=STRIDE_ACTIVE)
        {
            if (currentTime - llList2Integer(menusActive, i+2) > MENU_TIMEOUT) toRemove = [llList2Integer(menusActive, i)] + toRemove;
        }

        length = llGetListLength(toRemove);
        if (length > 0)
        {
            for(i=0;i<length;i++)
            {
                RemoveMenu(llList2Integer(toRemove, i), TRUE);
            }
        }        
    }
}

See also

• Script Library