utils.multilistbox
Lua function

utils.multilistbox

Summary

Display a dialog box with choices in it in a multiple selection list box

Prototype

result = utils.multilistbox (msg, title, tbl, default)


Description

This displays a dialog box with a predetermined list of items for the user to choose from, in the form of a multiple-selection listbox. If the user cancels the dialog box, or does not make a selection, nil is returned. Otherwise the key of the selected item is returned.

There are three similar functions that have the same arguments:


  • utils.choose - displays a dialog box with a combo-box in it (drop-down list)
  • utils.listbox - displays a dialog box with a list control in it - single selection
  • utils.multilistbox - displays a dialog box with a list control in it - multiple selections allowed


The utils.listbox function would be more suitable for longer lists, but that is probably partly personal preference.

The utils.multilistbox function allows multiple selections, so this is useful when you want the user to be able to select multiple items.

The calling sequence is:


result = utils.multilistbox ( msg, title, t, default )


The only required arguments are the message text and the table of choices (t).


  • msg = message to display (max 1000 characters)
  • title = title of box - if nil, defaults to "MUSHclient" (max 100 characters)
  • t - table of key/value pairs, as described below
  • default = table of default keys (nil for no default selection)


Return value = a table of the selected keys, or nil if nothing selected.

The third argument is a table of key/value pairs. The value is displayed, however the corresponding key is returned. The values are automatically sorted into ascending alphabetic order.

The fourth argument is a table of the keys of the wanted defaults. For no default selection just pass nil as the default.

Example:



t = { 
    fruit = "apple", 
    vegetable = "potato", 
    spice = "pepper", 
    herb = "parsley",
    } 

defaults = {
    fruit = true, 
    spice = true, 
    }

result = utils.multilistbox (
    "Choose a food", 
    "Foods ...", 
    t, 
    defaults
    )


Possible returned values would be:


  • nil - if no choice made or dialog cancelled
  • otherwise a table of chosen items (eg. { spice = true, fruit = true } )




Keys and values can be either strings or numbers. MUSHclient will distinguish between strings and numbers which are the same (eg. "10" and 10 are considered different keys).

See Also ...

Topics

DOC_lua_base Lua base functions
DOC_lua_bc Lua bc (big number) functions
DOC_lua_bit Lua bit manipulation functions
DOC_lua_coroutines Lua coroutine functions
DOC_lua_debug Lua debug functions
DOC_lua_io Lua io functions
DOC_lua_math Lua math functions
DOC_lua_os Lua os functions
DOC_lua_package Lua package functions
DOC_lua_rex Lua PCRE regular expression functions
DOC_lua Lua script extensions
DOC_lua_string Lua string functions
DOC_lua_tables Lua table functions
DOC_lua_utils Lua utilities
DOC_scripting Scripting

Lua functions

LUA_utils.base64decode utils.base64decode (Decode a string which was base-64 encoded)
LUA_utils.base64encode utils.base64encode (Encode a string with base-64 encoding)
LUA_utils.choose utils.choose (Display a combo box with choices in it)
LUA_utils.compress utils.compress (Compress a string)
LUA_utils.decompress utils.decompress (Decompress a string)
LUA_utils.editbox utils.editbox (Display a large message box and get free-format reply)
LUA_utils.edit_distance utils.edit_distance (Returns the Levenshtein Edit Distance between two words)
LUA_utils.filepicker utils.filepicker (Invokes the Windows standard "file picker" dialog box)
LUA_utils.fromhex utils.fromhex (Convert a string from hex)
LUA_utils.functionlist utils.functionlist (Returns a table of MUSHclient world function names)
LUA_utils.hash utils.hash (Hash a string, returning the hex codes)
LUA_utils.info utils.info (Information about directories)
LUA_utils.inputbox utils.inputbox (Display a message box and get free-format reply)
LUA_utils.listbox utils.listbox (Display a dialog box with choices in it in a single selection list box)
LUA_utils.md5 utils.md5 (Hash a string using the 128-bit MD5 algorithm)
LUA_utils.metaphone utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)
LUA_utils.msgbox utils.msgbox (Display a message box and get a response)
LUA_utils.readdir utils.readdir (Read a disk directory into a table)
LUA_utils.sha256 utils.sha256 (Hash a string using a 256-bit hash)
LUA_utils.spellcheckdialog utils.spellcheckdialog (Spell-checker dialog)
LUA_utils.split utils.split (Split a delimited string into a table)
LUA_utils.tohex utils.tohex (Convert a string into hex)
LUA_utils.utf8decode utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)
LUA_utils.utf8encode utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)
LUA_utils.utf8valid utils.utf8valid (Checks if a UTF-8 string is valid)
LUA_utils.xmlread utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.multilistbox)

DOC_contents Documentation contents page