doc/mp_interactive_dialog_boxes.txt

   1 Minimum Profit: Creating interactive dialog boxes
   2 =================================================
   3
   4 This document is a reference to the mp.form() function and associated
   5 tools that ease interaction with the user from inside the Minimum Profit
   6 Text Editor.
   7
   8 Alert boxes
   9 -----------
  10
  11 Alert boxes are simple popups or message notifications that interrupts the
  12 user with a message. Their usage is trivial:
  13
  14         mp.alert("It's coffee time!!!");
  15
  16 Confirmation boxes
  17 ------------------
  18
  19 Confirmation boxes are simple forms that show a message and ask for
  20 confirmation. The user response is returned as an integer value. Its use
  21 is also trivial:
  22
  23         local r = mp.confirm("File has changed. Save changes?");
  24
  25 The returned values can be 1 if user said _yes_, 2 if user said _no_, and
  26 0, if used cancelled.
  27
  28 Open and save file boxes
  29 ------------------------
  30
  31 Open and save file boxes are system-dependent dialog boxes that show a
  32 prompt and ask for a filename to open or save into. They both return the
  33 file name on confirmation or NULL on cancellation:
  34
  35         local r = mp.openfile("File to open:");
  36
  37         local s = mp.savefile("Save as:");
  38
  39 Forms
  40 -----
  41
  42 Forms can be created in MP by using the mp.form() function. It implements a
  43 simplified, common interface for GUI and text modes while trying to be as
  44 useful as possible.
  45
  46 The following is an example taken from mp_search.mpsl:
  47
  48         local t = mp.form( [
  49                 { 'label'       => L("Text to seek:"),
  50                   'type'        => 'text',
  51                   'history'     => 'search' },
  52                 { 'label'       => L("Case sensitive") ~ ':',
  53                   'type'        => 'checkbox',
  54                   'value'       => mp.config.case_sensitive_search }
  55         ] );
  56
  57 As can be seen, mp.form() accepts a list of hashes describing the fields
  58 to be shown to the user and returns an array with the filled values. On
  59 user cancellation, mp.form() return NULL; otherwise, an array with the
  60 same number of elements as the array sent as argument is returned, having
  61 each entered value in each element.
  62
  63 The following _widget_ types exist:
  64
  65  * text: A field to enter text.
  66  * password: A field to enter text, but hiding its input.
  67  * checkbox: A field to enter yes/no values.
  68  * list: A field to select an element from a given list of values.
  69
  70 Every widget can have some common attributes:
  71
  72  * value: The initial value.
  73  * label: A text string to be shown near the field, describing it.
  74
  75 Other attributes can exist for each widget.
  76
  77 Depending on the driver, a dialog box can show `OK' and `Cancel' buttons,
  78 and accept cancellation by hitting the `escape' hey.
  79
  80 Text widgets
  81 ~~~~~~~~~~~~
  82
  83 Text widgets are used, unsurprisingly, for entering free text. No limit
  84 exist on the string size nor the accepted character set. If a `value'
  85 attribute is set, it's shown as the default value, allowing edition.
  86
  87 The following additional attributes can be used in text widgets:
  88
  89  * history: A tag marking the history set. Every time a dialog is
  90    accepted (i.e. not cancelled), the entered value is stored in the
  91    history set named by this attribute. History is accesible by pressing
  92    the `cursor-up' and `cursor-down' keys.
  93
  94 Example:
  95
  96         local r = mp.form(
  97                 [
  98                         {
  99                         'type'  => 'text',
 100                         'label' => 'Enter your name:'
 101                         }
 102                 ]
 103         );
 104
 105         if (r != NULL)
 106                 mp.alert('Your name is ' ~ r[0] ~ '!');
 107
 108 Password widgets
 109 ~~~~~~~~~~~~~~~~
 110
 111 Password widgets are the same as text widgets, but its content is not
 112 shown. For each character, an asterisk or similar placeholder character is
 113 shown. No `history' attributes are allowed.
 114
 115 Example:
 116
 117         local r = mp.form(
 118                 [
 119                         {
 120                         'type'  => 'text',
 121                         'label' => 'Login:'
 122                         },
 123                         {
 124                         'type'  => 'password',
 125                         'label' => 'Password:'
 126                         }
 127                 ]
 128         );
 129
 130         if (r != NULL)
 131                 login_into_system(r[0], r[1]);
 132
 133 Checkbox widgets
 134 ~~~~~~~~~~~~~~~~
 135
 136 Checkbox widgets are used to set alternatives, i.e., values that can be
 137 true or false. Depending on the driver, they are shown as real checkboxes
 138 or [Y/N] questions. The initial `value' can be non-zero for _true_ and
 139 zero for _false_. On return, the value can be 1 or 0.
 140
 141         local r = mp.form(
 142                 [
 143                         {
 144                         'type'  => 'text',
 145                         'label' => 'Tab size:',
 146                         'value' => 8
 147                         },
 148                         {
 149                         'type'  => 'checkbox',
 150                         'label' => 'Convert to spaces:',
 151                         'value' => 0
 152                         }
 153                 ]
 154         );
 155
 156 List widgets
 157 ~~~~~~~~~~~~
 158
 159 List widgets are used to select one from an array of values. The `value'
 160 attribute is the initially selected item from the supplied list.
 161
 162 The additional attributes are:
 163
 164  * list: The mandatory list of values, as an array of strings.
 165
 166 On return, the value is the subscript of the selected item.
 167
 168 Example:
 169
 170         local r = mp.form(
 171                 [
 172                         {
 173                         'type'  => 'list',
 174                         'label' => 'Which C source file to open:',
 175                         'list'  => glob("*.c"),
 176                         'value' => 0
 177                         },
 178                         {
 179                         'type'  => 'checkbox',
 180                         'label' => 'Read only:',
 181                         'value' => 0
 182                         }
 183                 ]
 184         );
 185
 186 ----
 187 Angel Ortega <angel@triptico.com>