Module prompts

Common dialog boxes.

Functions

alert(message[, title]) Displays a message to the user.
confirm(question[, title]) Displays a yes/no question to the user.
flash(message[, msec]) Posts a message on the screen for a brief time.
get_password([message]) Asks the user for password.
input(question, [default], [title], [history]) Asks the user for input to type.
please_wait(message, callback[, ...]) Shows a “Please wait” sign for a potentially lengthy operation.
query([title,] question, answers) Queries the user for a choice.


Functions

alert(message[, title])

Displays a message to the user.

if you wish to examine a variable’s value, use devel.view instead.

This function, for the sake of convenience, is also exposed in the global namespace.

This function’s name (and that of confirm) was taken from the JavaScript world. input’s from Python’s.

  • This function is background-safe.
  • You may use this function even when the UI is not ready: the message in this case will be written to stdout.
confirm(question[, title])
Displays a yes/no question to the user.

Choosing “yes” returns true. Choosing “no”, or pressing ESC, returns false.

if prompts.confirm(T"Delete this file?") then
  mc.rm(file)
end

(This function is not background-safe.)

flash(message[, msec])
Posts a message on the screen for a brief time.

The user can dismiss the message earlier by hitting any key.

Don’t use this device for critical messages: it isn’t considered good usability.

If the amount of time, msec, isn’t specified, it will be calculated for you based on the length of the message.

get_password([message])

Asks the user for password.

Return the user input, or nil is the user cancels the dialog.

if prompts.get_password(T"Type the password for launching the A-bomb") == "top secret" then
  launch_missile()
end
  • This function is background-safe.
  • You may use this function even when the UI is not ready: the user will be asked to enter input through the raw terminal.
input(question, [default], [title], [history])

Asks the user for input to type. 

local age = prompts.input(T"What's your age?")
local lang = prompts.input(T"What's you mother tongue?", "English")
local food = prompts.input(T"What did you eat today?", -1, nil, "foods")

You may provide a default value to initialize the input with. The special value -1 initializes the input with the last value from the history.

The strings typed are kept in a shared history. If you wish your dialog to have a private history, provide some unique history string.

If the user cancels the dialog, the function returns nil. This is different than not typing any input, in which case an empty string is returned.

  • This function is background-safe.
  • You may use this function even when the UI is not ready: the user will be asked to enter input through the raw terminal.
please_wait(message, callback[, ...])

Shows a “Please wait” sign for a potentially lengthy operation.

This function runs some code, specified by the callback parameter, and while doing this it shows a “Please wait” dialog.

Use this function when running a long task (e.g., when using os.execute or io.popen) so your user knows why he has to incur the delay.

(Alternatively, instead of using this function, split your lengthy task into smaller slices and run them in a timer/thread. This will keep the UI responsive.)

prompts.please_wait(T"Searching for UnicodeData.txt file.", function()
  unicodedata_path = io.popen("locate -n 1 -e /UnicodeData.txt"):read()
end)

This function returns the callback’s result. So you can replace any:

one, two, three = func(four, five)

with:

one, two, three = prompts.please_wait(T"Doing something", func, four, five)
query([title,] question, answers)
Queries the user for a choice.

Displays possible choices for the users, as buttons.

local answer = prompts.query(Y"Do it?", {
  {T"Yes", "yes"},
  {T"Maybe", "maybe"},
  {T"No"}
}) or "no"

(Note how we equate the “No” button with pressing ESC by doing or "no".)

The title, if provided, is passed as-is to ui.Dialog(), so if you want an error dialog, do:

local answer = prompts.query({T"Important question", colorset="alarm"},
  Y"Do it?", {
    ...
  })

See more examples here.

Parameters:

  • title Optional title for the dialog.
  • question A string.
  • answers A list of possible answers. Will be shown as buttons. Each answer is a list: its first element is the label and its second (optional) element is the result value.
generated by LDoc 1.4.3 Last updated 2016-08-23 17:29:40