MUSHclient documentation: contents

utils.filterpicker

utils.filterpicker
Summary Display a dialog box which filters its contents as you type Prototype `result = utils.filterpicker (tbl, title, initial_filter, no_sort, filter_function, filter_prepare_function)` Description This displays a dialog box with a predetermined list of items for the user to choose from, in the form of a multi-column table. 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 is a "filter" box, which if you type into, reduces the visible contents of the dialog to whatever matches the filter (not case-sensitive). This could be used to reduce the displayed items to (for example) shops. More examples, explanations, and screenshots are at: http://mushclient.com/forum/?id=10618 The calling sequence is: `result = utils.filterpicker (t, title, initial_filter)` The only required arguments is the table of choices (t). t - table of key/value pairs, as described below title = title of box - if nil, defaults to "Filter" (max 100 characters) initial_filter = initial filter value - defaults to no filter no_sort - if true, the list is not sorted alphabetically filter_function - optionally filter dynamically based on a function call. filter_prepare_function - function called each time something is typed into the filter box. Return value = the key of what they selected, or nil if cancelled, or nothing selected. The first 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 third argument is the initial value for the filter box. If empty, no filtering initially takes place. The fourth argument suppresses sorting of the list, if true. The fifth argument (filter_function) lets you decide at run-time via a function call whether or not to show each item. This function is passed the current filter (what is wanted), the key of the item in question, and the value of the item in question. So, for example, if you wanted the filter field to contain a number which indicated the length of words to be shown, you might write: `function filter_function (wanted, key, value) local length = tonumber (wanted) if not length then return false end -- if not number return #value == length end -- filter` Every time the user types something into the "filter" box the filter function is called once for every item in the key/value table (to see if the item should be displayed). The sixth argument (filter_prepare_function) lets you prepare for filtering. This is called once every time the user types something into the "filter" box. This could be used to do a FTS (full text search) of a database, based on the filter text, to find all matching rows. Then the filter function itself would simply see if a row had been found or not. For example: `function filter_prepare_function (wanted) wanted_rooms = {} for row in db:nrows ("SELECT uid FROM rooms WHERE name MATCH '" .. wanted .. "'") do wanted_rooms [row.uid] = true end end -- filter_prepare_function` Example of use: `print (utils.filterpicker ({ "apples", "bananas", "peaches", "cream" }, "Foods ..." ))` 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.filterpicker (t, "Foods ...") 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: `t = { fruit = "apple", vegetable = "potato", spice = "pepper", herb = "parsley", } result = utils.filterpicker (t, "Foods ...") 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.choose - Display a combo box with choices in it 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.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.filterpicker)

Summary

Display a dialog box which filters its contents as you type

Prototype

result = utils.filterpicker (tbl, title, initial_filter, no_sort, filter_function, filter_prepare_function)

Description

This displays a dialog box with a predetermined list of items for the user to choose from, in the form of a multi-column table. 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 is a "filter" box, which if you type into, reduces the visible contents of the dialog to whatever matches the filter (not case-sensitive). This could be used to reduce the displayed items to (for example) shops.

More examples, explanations, and screenshots are at:

http://mushclient.com/forum/?id=10618

The calling sequence is:


result = utils.filterpicker (t, title, initial_filter)

The only required arguments is the table of choices (t).

t - table of key/value pairs, as described below
title = title of box - if nil, defaults to "Filter" (max 100 characters)
initial_filter = initial filter value - defaults to no filter
no_sort - if true, the list is not sorted alphabetically
filter_function - optionally filter dynamically based on a function call.
filter_prepare_function - function called each time something is typed into the filter box.

Return value = the key of what they selected, or nil if cancelled, or nothing selected.

The first 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 third argument is the initial value for the filter box. If empty, no filtering initially takes place.

The fourth argument suppresses sorting of the list, if true.

The fifth argument (filter_function) lets you decide at run-time via a function call whether or not to show each item.

This function is passed the current filter (what is wanted), the key of the item in question, and the value of the item in question.

So, for example, if you wanted the filter field to contain a number which indicated the length of words to be shown, you might write:


function filter_function (wanted, key, value)
  local length = tonumber (wanted)
  if not length then
     return false
  end -- if not number

  return #value == length
end -- filter

Every time the user types something into the "filter" box the filter function is called once for every item in the key/value table (to see if the item should be displayed).

The sixth argument (filter_prepare_function) lets you prepare for filtering. This is called once every time the user types something into the "filter" box. This could be used to do a FTS (full text search) of a database, based on the filter text, to find all matching rows. Then the filter function itself would simply see if a row had been found or not.

For example:


function filter_prepare_function (wanted)
  wanted_rooms = {}
  for row in db:nrows ("SELECT uid FROM rooms WHERE name MATCH '" .. wanted .. "'") do
    wanted_rooms [row.uid] = true
  end
end -- filter_prepare_function

Example of use:


print (utils.filterpicker ({ "apples", "bananas", "peaches", "cream" }, "Foods ..." ))

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.filterpicker (t, "Foods ...")

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:


t = { 
    fruit = "apple", 
    vegetable = "potato", 
    spice = "pepper", 
    herb = "parsley",
    } 
result = utils.filterpicker (t, "Foods ...")

if result then
  print ("You chose key", result, "which is", t [result])
else
  print "Nothing chosen"
end -- if

Possible returned values would be: