User interaction

These functions allow scripts to interact with the user. Perhaps, it is not a very bright idea to irritate users by using any of them way too often so please use these functions with care. However, feel free to use them for debugging purposes but do not forget to remove all debugging tools before releasing your script.

WarningBox(Text[, Title])
ErrorBox(Text[, Title])
UserAnswerIsYes = YesNoBox(Text[, Title])
UserChoice = Choice(Text, Table[, DefaultChoice])

WarningBox(Text[, Title])

This function lets you show a warning message to the [unsuspecting] user. The first mandatory parameter is a text string to display to the user. The second optional parameter is a text string to show in the title of the box. If this parameter is omitted, the string "TempLuator Warning" will be used for the title. Here is an example:

IMAGE_DOS_SIGNATURE = 0x5A4D

if PeekUI16() ~= IMAGE_DOS_SIGNATURE then
WarningBox("This is not a 'MZ' file")
end

ErrorBox(Text[, Title])

This function is almost the same as the previous one with an important exception: after showing the box, it stops execution of the script and invokes internal error handler, which in turn types the same message in the output pane along with usual error information. If the Title parameter is omitted, the string "TempLuator Error" will be used for the box title.

UserAnswerIsYes = YesNoBox(Text[, Title])

This function lets you ask the user if (s)he want to perform an action. Again, the mandatory Text parameter is the text that will be displayed to the user. The optional Title parameter defines the title (the string "TempLuator Question" will be used if this parameter is omitted). The function returns a single boolean value which is true if the user's answer was "yes, please!" or false otherwise.

-- wow, it's time to ask the user
local KillAliens = YesNoBox("Alien invasion detected!\nDo you want to press the Red Button?", "Panic!")

UserChoice = Choice(Text, Table[, DefaultChoice])

This function allows you to ask the user for his/her decision in more complex situations than simple yes/no selection. The Text parameter (just a string) is a question to display to the user. The Table parameter defines all possible choices. It must be a non-empty Lua table containing strings, each of which defines a possible user choice. Both these parameters are mandatory. The third optional parameter (a number) defines which choice to select by default. If it is equal to 0 or omitted, the very first choice gets selected. The same is true when this parameter is greater than the number of possible choices (that is, the number of entries in the table). The function return value is the zero-based index of the user selection or nil if the user has pressed Esc or an error has occured.

Here is an example which demonstrates a way to ask the user which string encoding he wants to use throughout the rest of the script:

-- all available answers must be defined in a table
local Answers = { "UTF8", "UTF7", "CP866" }

-- ask the user. By default we select UTF7 and its zero-based index in the table is 1
local EncodingIdx = Choice("Select encoding", Answers, 1)

-- important! Choice() return values are zero-based so we add one to index the table
if EncodingIdx then
    print("User choice is: ", Answers[EncodingIdx + 1])
else
    print("Wow! User's keyboard is equipped with an Escape key!")
end

Please note that the Choice() function expects and returns zero-based indices. In the example above we used the function return value to index its input table. By default, Lua uses 1-based indices so we have to add one to select the proper entry. Here is a neat trick to simplify indexing, just note how we define our table:

-- all available answers must be defined in a table
local Answers = { [0] = "UTF8", [1] = "UTF7", [2] = "CP866" }