utils.multilistbox

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

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 dialog cancelled
• otherwise a table of chosen items (eg. { spice = true, fruit = true } ) - this table might be empty if nothing was chosen

---

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).