<h1 id="form">FORM</h1>

<p>f = FORM(formMap)</p>

<p>Creates a form object <code>f</code> from a MAP variable

<code>formMap</code>. Form object <code>f</code> gives access to the

following GUI elements:</p>

<li>Push button</li>

<li>Label</li>

<li>Hyperlinked text</li>

<li>Listbox</li>

<li>Dropdown listbox</li>

<li>Single or multi-line text input</li>

<li>Image button</li>

<p>In listboxes and dropdown listboxes press and hold mouse button to

scroll through the items. Alternatively arrow keys can be used. Press

return or space for selecting the highlighted item.</p>

<h3 id="the-form-object">The form object</h3>

<p><code>f = form(formMAP)</code> provides access to the following

sub-commands of the form object <code>f</code>:</p>

<col style="width: 29%" />

<col style="width: 70%" />

<tr class="header">

<th>Sub-command</th>

<th>Description</th>

<tr class="odd">

<td>doEvents()</td>

<td>Process system events for mouse and keyboard handling.</td>

<tr class="even">

<td>close()</td>

<td>Closes the active FORM.</td>

<tr class="odd">

<td>refresh(n)</td>

<td><code>n = 1</code> copy the UI state into the FORM input variables

<code>f.inputs</code>. <code>n = 0</code> update the UI state using the

FORM input variables <code>f.inputs</code>.</td>

<p>The form object <code>f</code> may contain the following

properties:</p>

<tr class="header">

<th>Property</th>

<th>Description</th>

<tr class="odd">

<td>value</td>

<td>The value from the active input field.</td>

<tr class="even">

<td><strong>inputs</strong></td>

<td>Array of inputs.</td>

<tr class="odd">

<td>focus</td>

<td>Index to the focused input.</td>

<h3 id="defining-the-input-fields">Defining the input fields</h3>

<p><code>inputs</code> is an array of type MAP, each element may contain

the following attributes:</p>

<col style="width: 53%" />

<col style="width: 46%" />

<tr class="header">

<th>Attribute</th>

<th>Description</th>

<tr class="odd">

<td>x</td>

<td>X coordinate.</td>

<tr class="even">

<td>y</td>

<td>Y coordinate.</td>

<tr class="odd">

<td>width</td>

<td>Width.</td>

<tr class="even">

<td>height</td>

<td>Height.</td>

<tr class="odd">

<td>value</td>

<td>The internal value associated with the input.</td>

<tr class="even">

<td>label</td>

<td>The display label for the input.</td>

<tr class="odd">

<td>name</td>

<td>The name of the input.</td>

<tr class="even">

<td><strong>type</strong></td>

<td>The type of input, see below.</td>

<tr class="odd">

<td>help</td>

<td>Listbox or single line text input help text.</td>

<tr class="even">

<td>backgroundColor</td>

<td>Background color.</td>

<tr class="odd">

<td>color</td>

<td>Forground color.</td>

<tr class="even">

<td>isExit</td>

<td>Whether clicking the input exits the current program.</td>

<tr class="odd">

<td>isExternal</td>

<td>Whether the <code>link</code> field opens in an external

browser.</td>

<tr class="even">

<td>resizable</td>

<td>Whether the field can be resized.</td>

<tr class="odd">

<td>visible</td>

<td>Whether the input field is visible.</td>

<tr class="even">

<td>selectedIndex</td>

<td>The selected item in a listbox or choice.</td>

<tr class="odd">

<td>length</td>

<td>Length of a TEXT input field in number of characters.</td>

<tr class="even">

<td>noFocus</td>

<td>The input cannot receive focus.</td>

<tr class="odd">

<td>onclick</td>

<td>SUB to invoke when clicked.</td>

<p>The type attribute can be one of the following:</p>

<tr class="header">

<th>Type</th>

<th>Description</th>

<tr class="odd">

<td>“button”</td>

<td>Push button.</td>

<tr class="even">

<td>“label”</td>

<td>Display label.</td>

<tr class="odd">

<td>“link”</td>

<td>Hyperlinked text.</td>

<tr class="even">

<td>“listbox”</td>

<td>Listbox.</td>

<tr class="odd">

<td>“choice”</td>

<td>Dropdown listbox.</td>

<tr class="even">

<td>“text”</td>

<td>Single or multi-line text input.</td>

<tr class="odd">

<td>“image”</td>

<td>Image button.</td>

<h3 id="change-or-read-the-gui-elements">Change or read the GUI

elements</h3>

<p>Once the GUI elements are rendered on screen they can be changed for

example to respond to user input. By calling <code>f.refresh(1)</code>

the current state of the GUI elements will be copied to <code>f</code>.

The content of <code>f</code> is rendered to screen, when calling

<code>f.refresh(0)</code>. <code>f.inputs</code> is an array of MAP

variables. The first element of that array is the first GUI element

added to <code>formMap.inputs</code>. For example the color of the first

element can be changed:</p>

<pre><code>f.inputs[0].color = 12

f.refresh(0)</code></pre>

<p>To get a list of all available elements of the n-th GUI element, you

can simply use <code>print f.inputs[n]</code>.</p>

id="example-1-creating-a-push-button-using-callback-function">Example 1:

Creating a push button using callback function</h3>

<p>When using buttons in combination with callback functions, the

<code>doEvents()</code> function is not necessary. Without this function

the execution of the program will not be blocked. In the following

example a number will be incremented in a while loop and printed to the

screen. When the button is pressed, the callback function is executed

and will block the program until the callback function ends.</p>

<pre><code>button.type = &quot;button&quot;

button.x = 120

button.y = 120

button.label = &quot;Button&quot;

button.backgroundcolor = rgb(60, 60, 60)

button.onclick = @ButtonClicked &#39; Callback function, definition see below

formMAP.inputs &lt;&lt; button

f = form(formMAP)

while 1

ii++

locate 0,0: print ii

delay(100)

wend

f.close()

sub ButtonClicked()

locate 1,0

Clicked++

print &quot;Button clicked &quot; + Clicked + &quot; times&quot;

end

<h3 id="example-2-creating-a-push-button-using-doevents-result">Example

2: Creating a push button using doEvents result</h3>

<pre><code>button.type = &quot;button&quot;

button.x = 120

button.y = 120

button.label = &quot;Button&quot;

button.backgroundcolor = rgb(60, 60, 60)

button.value = 1 &#39; unique value to identify the button

formMAP.inputs &lt;&lt; button

f = form(formMAP)

while 1

f.doEvents()

if(f.value == 1) then

ii++

at 0,0

print &quot;Button cklicked &quot; + ii + &quot; times.&quot;

endif

wend

f.close()</code></pre>

<h3 id="example-3-creating-a-label">Example 3: Creating a label</h3>

<pre><code>l.type = &quot;label&quot;

l.x = 120

l.y = 120

l.label = &quot;Label&quot;

l.color = rgb(255, 60, 60)

f.inputs &lt;&lt; l

f = form(f)

while 1

f.doEvents()

wend

f.close()</code></pre>

<h3 id="example-4-creating-a-link-to-an-external-website">Example 4:

Creating a link to an external website</h3>

<pre><code>l.type = &quot;link&quot;

l.x = 120

l.y = 120

l.label = &quot;Link to SmallBASIC website&quot;

l.value = &quot;https://smallbasic.github.io&quot;

l.isExternal = true

l.color = rgb(100, 100, 255)

f.inputs &lt;&lt; l

f = form(f)

while 1

f.doEvents()

wend

f.close()</code></pre>

<h3 id="example-5-creating-a-listbox">Example 5: Creating a listbox</h3>

<pre><code>l.type = &quot;listbox&quot;

l.x = 120

l.y = 120

l.height = 200

l.width = 100

l.value = &quot;cats|dogs|fish|birds|insects&quot;

&#39; alternative way is to pass an array:

&#39; l.value = [&quot;cats&quot;, &quot;dogs&quot;, &quot;fish&quot;, &quot;birds&quot;, &quot;insects&quot;]

l.color = rgb(255, 255, 255)

l.backgroundColor = rgb(100, 100, 100)

f.inputs &lt;&lt; l

f = form(f)

while 1

f.doEvents()

&#39; Check for value of the active input field

if (len(f.value) &gt; 0) then

at 0,0

print f.value; &quot; &quot;

end if

wend

f.close()</code></pre>

<h3 id="example-6-creating-a-dropdown-listbox">Example 6: Creating a

dropdown listbox</h3>

<pre><code>l.type = &quot;choice&quot;

l.x = 120

l.y = 120

l.width = 100

l.value = &quot;cats|dogs|fish|birds|insects&quot;

&#39; alternative way is to pass an array:

&#39; l.value = [&quot;cats&quot;, &quot;dogs&quot;, &quot;fish&quot;, &quot;birds&quot;, &quot;insects&quot;]

l.color = rgb(255, 255, 255)

l.backgroundColor = rgb(100, 100, 100)

f.inputs &lt;&lt; l

f = form(f)

while 1

f.doEvents()

&#39; Check for value of the active input field

if (len(f.value) &gt; 0) then

at 0,0

print f.value; &quot; &quot;

end if

wend

f.close()</code></pre>

<h3 id="example-7-creating-a-text-input-field">Example 7: Creating a

text input field</h3>

<pre><code>t.type = &quot;text&quot;

t.x = 120

t.y = 120

t.width = 300

t.value = &quot;Add more text&quot;

&#39; t.height = 100 &#39; if hight is not defined, single line field

t.color = rgb(255, 255, 255)

t.backgroundColor = rgb(100, 100, 100)

t.length = 50 &#39; number of characters

&#39; create additionally an OK-Button to update the form object

&#39; otherwise the text field blocks loop

b.type = &quot;button&quot;

b.x = 120 + t.width + 10

b.y = 120

b.label = &quot;OK&quot;

b.backgroundcolor = rgb(60, 60, 60)

b.onclick = @OKButtonClicked

f.inputs &lt;&lt; t

f.inputs &lt;&lt; b

f = form(f)

while 1

f.doEvents()

wend

f.close()

sub OKButtonClicked()

f.refresh(1) &#39; Update the form object

at 0,0

print f.inputs[0].value &#39; Text field is the first element added to the formMAP

end</code></pre>

<h3 id="example-8-image-button-using-callback-function">Example 8: Image

button using callback function</h3>

<p>In this example a callback function will be used. If you want to use

the doEvents result instead, have a look at example 2.</p>

<pre><code>&#39; Create a simple button and save it as png

&#39; If you have already an image for you button,

&#39; this part is not necessary.

circle 100,100,100 color 15 filled

ButtonImage = image(0,0,200,200)

ButtonImage.save(&quot;button.png&quot;)

cls

&#39; Define image button

button.type = &quot;image&quot;

button.name = &quot;button.png&quot;

button.x = 120

button.y = 120

button.onclick = @ButtonClicked     &#39; Callback function, definition see below.

formMAP.inputs &lt;&lt; button

f = form(formMAP)

while 1

  f.doEvents()

wend

f.close()

sub ButtonClicked()

  at 0,0

  Clicked++

  print &quot;Button clicked &quot; + Clicked + &quot; times&quot;

end</code></pre>

<h3 id="example-9-one-more-example">Example 9: One more example</h3>

<pre><code>f.handleKeys = 0

&#39; create some buttons

button1.y = 120

button1.label = &quot;Button1&quot;

button1.value = &quot;valueofButton1&quot;

button1.backgroundcolor = rgb(255,0,0)

button1.onclick = @HelloWorld &#39;this prints on load

button2.x = -1

button2.y = 120

button2.label = &quot;Button2&quot;

button2.value = &quot;valueofButton2&quot;

button3.value = &quot;cats&quot;

button3.x = -1

button3.y = 120

button3.background = 223344

b4.type = &quot;choice&quot;

b4.value = &quot;cats|dogs|Fish|cats|dogs|Fish|cats|dogs|Fish|cats|dogs|Fish&quot;

b4.selectedIndex = 2

b4.x = -1

b4.y = 120

b5.type = &quot;list&quot;

b5.value = &quot;cats|dogs|Fish|cats|dogs|Fish|cats|dogs|Fish|cats|dogs|Fish|end|lol&quot;

b5.x = -1

b5.y = 120

b5.height = 120

b6.type = &quot;text&quot;

b6.value = &quot;cats&quot;

b6.length=30

b6.x = -1

b6.y = 120

b6.width = 50

b6.noFocus = 0

&#39; add buttons to the form

f.inputs &lt;&lt; button1

f.inputs &lt;&lt; button2

f.inputs &lt;&lt; button3

f.inputs &lt;&lt; b4

f.inputs &lt;&lt; b5

f.inputs &lt;&lt; b6

f.backgroundcolor = &quot;green&quot;

&#39; at this stage &#39;f&#39; is just a plain user defined structure (map)

&#39; after calling FORM, &#39;f&#39; becomes a system form object with three special functions

&#39; doEvents, close and refresh (see sokoban.bas for refresh)

f = form(f)

&#39; the string version of the form is JSON (see https://en.wikipedia.org/wiki/JSON)

TSAVE &quot;f.frm&quot;, f

while 1

&#39; pump the system event queue

f.doEvents()

&#39; process the event

in$ = inkey

at 0,0

if len(in$)&gt;1 then

flag= asc(left(in$,1))

keychar =right(in$,1)

n= asc(keychar)

if (flag == 1)

? &quot;Ctrl : &quot;;keychar ; &quot; &quot;

else if (flag == 2)

? &quot;Alt : &quot;; keychar

else if (flag == 3)

? &quot;Ctrl+Alt: &quot;; keychar ; &quot; &quot;

else

? &quot;Arrow: &quot;; n ; &quot; &quot;

end if

else

vkey = asc(in$)

if (vkey == 8) then

? &quot;backspace!&quot;

else if (vkey == 127) then

? &quot;delete !&quot;

else

? &quot; key= &quot;; in$; &quot; &quot;; vkey

endif

endif

if b6.value &lt;&gt; &quot;cats&quot; then ? b6.value

if (len(f.value) &gt; 0) then

print f.value; &quot; &quot;

end if

wend

f.close()

func HelloWorld

? &quot;hello world&quot;

end</code></pre>