# Creating interactive dialog boxes

     Angel Ortega <angel@triptico.com>

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

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

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

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

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:

text | A field to enter text.
password | A field to enter text, but hiding its input.
checkbox | A field to enter yes/no values.
list | A field to select an element from a given list of values.

Every widget can have some common attributes:

value | The initial value.
label | A text string to be shown near the field, describing it.

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

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:

history | A tag marking the history set. Every time a dialog is accepted (i.e. not cancelled), the entered value is stored in the history set named by this attribute. History is accesible by pressing the `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

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

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

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:

list | The mandatory list of values, as an array of strings.

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
     			}
     		]
     	);

Angel Ortega <angel@triptico.com>