This document is a reference to the mp.form() function and associated
tools that ease interaction with the user from inside the Minimum Profit
Text Editor.
Alert boxes are simple popups or message notifications that interrupts the user with a message. Their usage is trivial:
mp.alert("It's coffee time!!!");
Confirmation boxes are simple forms that show a message and ask for confirmation. The user response is returned as an integer value. Its use is also trivial:
local r = mp.confirm("File has changed. Save changes?");
The returned values can be 1 if user said yes, 2 if user said no, and 0, if used cancelled.
Open and save file boxes are system-dependent dialog boxes that show a prompt and ask for a filename to open or save into. They both return the file name on confirmation or NULL on cancellation:
local r = mp.openfile("File to open:");
local s = mp.savefile("Save as:");
Forms can be created in MP by using the mp.form() function. It implements a
simplified, common interface for GUI and text modes while trying to be as
useful as possible.
The following is an example taken from mp_search.mpsl:
local t = mp.form( [
{ 'label' => L("Text to seek:"),
'type' => 'text',
'history' => 'search' },
{ 'label' => L("Case sensitive") ~ ':',
'type' => 'checkbox',
'value' => mp.config.case_sensitive_search }
] );
As can be seen, mp.form() accepts a list of hashes describing the fields
to be shown to the user and returns an array with the filled values. On
user cancellation, mp.form() return NULL; otherwise, an array with the
same number of elements as the array sent as argument is returned, having
each entered value in each element.
The following widget types exist:
Every widget can have some common attributes:
Other attributes can exist for each widget.
Depending on the driver, a dialog box can show OK and Cancel buttons,
and accept cancellation by hitting the escape hey.
Text widgets are used, unsurprisingly, for entering free text. No limit
exist on the string size nor the accepted character set. If a value
attribute is set, it's shown as the default value, allowing edition.
The following additional attributes can be used in text widgets:
cursor-up and cursor-down keys.
Example:
local r = mp.form(
[
{
'type' => 'text',
'label' => 'Enter your name:'
}
]
);
if (r != NULL)
mp.alert('Your name is ' ~ r[0] ~ '!');
Password widgets are the same as text widgets, but its content is not
shown. For each character, an asterisk or similar placeholder character is
shown. No history attributes are allowed.
Example:
local r = mp.form(
[
{
'type' => 'text',
'label' => 'Login:'
},
{
'type' => 'password',
'label' => 'Password:'
}
]
);
if (r != NULL)
login_into_system(r[0], r[1]);
Checkbox widgets are used to set alternatives, i.e., values that can be
true or false. Depending on the driver, they are shown as real checkboxes
or [Y/N] questions. The initial value can be non-zero for true and
zero for false. On return, the value can be 1 or 0.
local r = mp.form(
[
{
'type' => 'text',
'label' => 'Tab size:',
'value' => 8
},
{
'type' => 'checkbox',
'label' => 'Convert to spaces:',
'value' => 0
}
]
);
List widgets are used to select one from an array of values. The value
attribute is the initially selected item from the supplied list.
The additional attributes are:
On return, the value is the subscript of the selected item.
Example:
local r = mp.form(
[
{
'type' => 'list',
'label' => 'Which C source file to open:',
'list' => glob("*.c"),
'value' => 0
},
{
'type' => 'checkbox',
'label' => 'Read only:',
'value' => 0
}
]
);
Add a comment
Note: These comments won't be published until confirmed by a human being, so don't bother sending spam.