Summary
Display a combo box with choices in it
Prototype
result = utils.choose (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 combo-box. 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.choose ( 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 = default key - defaults to no selection
Return value = the key of what they selected, or nil if cancelled, or 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 the key (string or number) which corresponds to the wanted default selection. If it does not correspond to any key in the table then no item will be selected. For no default selection just pass nil as the default.
Example:
print (utils.choose ("Your favourite", "Foods ...", { "apples", "bananas", "peaches", "cream" } ))
Possible returned values would be:
nil - if no choice made or dialog cancelled
1 - apples chosen
2 - bananas chosen
3 - peaches chosen
4 - cream chosen
(Note that peaches would actually be shown 4th in the list as the list is sorted).
To convert from the key back to the value, simply index into your table. Eg.
t = { "apples", "bananas", "peaches", "cream" }
result = utils.choose ("Your favourite", "Foods ...", t)
if result then
print ("You chose", t [result])
else
print "Nothing chosen"
end -- if
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).
Here is an example of using string keys, and supplying a default choice:
t = {
fruit = "apple",
vegetable = "potato",
spice = "pepper",
herb = "parsley",
}
result = utils.choose ("Choose a food", "Foods ...", t, "fruit")
if result then
print ("You chose key", result, "which is", t [result])
else
print "Nothing chosen"
end -- if
Possible returned values would be:
nil - if no choice made or dialog cancelled
"fruit" - apple chosen
"vegetable" - potato chosen
"spice" - pepper chosen
"herb" - parsley chosen
The return value will be one of the following types:
nil - if no selection made or dialog cancelled
string - if an item with a string key is selected
number - if an item with a numeric key is selected
See Also ...
Lua functions
utils.activatenotepad - Actvitates the specified notepad window
utils.appendtonotepad - Appends text to the specified notepad window
utils.base64decode - Decode a string which was base-64 encoded
utils.base64encode - Encode a string with base-64 encoding
utils.callbackslist - Returns a table of plugin callback function names
utils.colourcube - Changes the colour cube used by 256-colour ANSI codes
utils.compress - Compress a string
utils.decompress - Decompress a string
utils.directorypicker - Invokes the Windows standard "directory picker" dialog box
utils.editbox - Display a large message box and get free-format reply
utils.edit_distance - Returns the Levenshtein Edit Distance between two words
utils.filepicker - Invokes the Windows standard "file picker" dialog box
utils.filterpicker - Display a dialog box which filters its contents as you type
utils.fontpicker - Invokes the Windows standard "font picker" dialog box
utils.fromhex - Convert a string from hex
utils.functionlist - Returns a table of MUSHclient world function names
utils.getfontfamilies - Returns all fonts available to Windows
utils.glyph_available - Returns the glyph index of a glyph (character) in a font
utils.hash - Hash a string, returning the hex codes
utils.info - Information about directories, locale, etc.
utils.infotypes - Returns a table of all GetInfo type selectors
utils.inputbox - Display a message box and get free-format reply
utils.listbox - Display a dialog box with choices in it in a single selection list box
utils.md5 - Hash a string using the 128-bit MD5 algorithm
utils.menufontsize - Alters the size of the font used in menus
utils.metaphone - Returns metaphones (sound-alike codes) for the supplied word
utils.msgbox - Display a message box and get a response
utils.multilistbox - Display a dialog box with choices in it in a multiple selection list box
utils.readdir - Read a disk directory into a table
utils.reload_global_prefs - Forces global preferences file to be reloaded
utils.sendtofront - Bring a window to the front
utils.sha256 - Hash a string using a 256-bit hash
utils.shellexecute - Executes a Windows "shell" command
utils.spellcheckdialog - Spell-checker dialog
utils.split - Split a delimited string into a table
utils.timer - Returns the high-resolution timer output
utils.tohex - Convert a string into hex
utils.umsgbox - Display a message box and get a response (Unicode)
utils.utf8convert - Encodes a string into a UTF-8 string
utils.utf8decode - Encodes a series of Unicode codes into a UTF-8 string
utils.utf8encode - Encodes a series of Unicode codes into a UTF-8 string
utils.utf8sub - Returns a substring of a UTF-8 string
utils.utf8valid - Checks if a UTF-8 string is valid
utils.xmlread - Parses an XML string into a nested table
Topics
Lua base functions
Lua bc (big number) functions
Lua bit manipulation functions
Lua coroutine functions
Lua debug functions
Lua io functions
Lua LPEG library
Lua math functions
Lua os functions
Lua package functions
Lua PCRE regular expression functions
Lua script extensions
Lua string functions
Lua syntax
Lua table functions
Lua utilities
Scripting
Scripting callbacks - plugins
(Help topic: lua=utils.choose)