f = FORM(formMap)
Creates a form object f from a MAP variable formMap. Form object f gives access to the following GUI elements:
- Push button
- Label
- Hyperlinked text
- Listbox
- Dropdown listbox
- Single or multi-line text input
- Image button
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.
f = form(formMAP) provides access to the following sub-commands of the form object f:
| Sub-command | Description |
|---|---|
| doEvents() | Process system events for mouse and keyboard handling. |
| close() | Closes the active FORM. |
| refresh(n) | n = 1 copy the UI state into the FORM input variables f.inputs. n = 0 update the UI state using the FORM input variables f.inputs. |
The form object f may contain the following properties:
| Property | Description |
|---|---|
| value | The value from the active input field. |
| inputs | Array of inputs. |
| focus | Index to the focused input. |
inputs is an array of type MAP, each element may contain the following attributes:
| Attribute | Description |
|---|---|
| x | X coordinate. |
| y | Y coordinate. |
| width | Width. |
| height | Height. |
| value | The internal value associated with the input. |
| label | The display label for the input. |
| name | The name of the input. |
| type | The type of input, see below. |
| help | Listbox or single line text input help text. |
| backgroundColor | Background color. |
| color | Forground color. |
| isExit | Whether clicking the input exits the current program. |
| isExternal | Whether the link field opens in an external browser. |
| resizable | Whether the field can be resized. |
| visible | Whether the input field is visible. |
| selectedIndex | The selected item in a listbox or choice. |
| length | Length of a TEXT input field in number of characters. |
| noFocus | The input cannot receive focus. |
| onclick | SUB to invoke when clicked. |
The type attribute can be one of the following:
| Type | Description |
|---|---|
| "button" | Push button. |
| "label" | Display label. |
| "link" | Hyperlinked text. |
| "listbox" | Listbox. |
| "choice" | Dropdown listbox. |
| "text" | Single or multi-line text input. |
| "image" | Image button. |
Once the GUI elements are rendered on screen they can be changed for example to respond to user input. By calling f.refresh(1) the current state of the GUI elements will be copied to f. The content of f is rendered to screen, when calling f.refresh(0). f.inputs is an array of MAP variables. The first element of that array is the first GUI element added to formMap.inputs. For example the color of the first element can be changed:
f.inputs[0].color = 12 f.refresh(0) To get a list of all available elements of the n-th GUI element, you can simply use print f.inputs[n].
When using buttons in combination with callback functions, the doEvents() 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.
button.type = "button" button.x = 120 button.y = 120 button.label = "Button" button.backgroundcolor = rgb(60, 60, 60) button.onclick = @ButtonClicked ' Callback function, definition see below formMAP.inputs << button f = form(formMAP) while 1 ii++ locate 0,0: print ii delay(100) wend f.close() sub ButtonClicked() locate 1,0 Clicked++ print "Button clicked " + Clicked + " times" end button.type = "button" button.x = 120 button.y = 120 button.label = "Button" button.backgroundcolor = rgb(60, 60, 60) button.value = 1 ' unique value to identify the button formMAP.inputs << button f = form(formMAP) while 1 f.doEvents() if(f.value == 1) then ii++ at 0,0 print "Button cklicked " + ii + " times." endif wend f.close() l.type = "label" l.x = 120 l.y = 120 l.label = "Label" l.color = rgb(255, 60, 60) f.inputs << l f = form(f) while 1 f.doEvents() wend f.close() l.type = "link" l.x = 120 l.y = 120 l.label = "Link to SmallBASIC website" l.value = "https://smallbasic.github.io" l.isExternal = true l.color = rgb(100, 100, 255) f.inputs << l f = form(f) while 1 f.doEvents() wend f.close() l.type = "listbox" l.x = 120 l.y = 120 l.height = 200 l.width = 100 l.value = "cats|dogs|fish|birds|insects" ' alternative way is to pass an array: ' l.value = ["cats", "dogs", "fish", "birds", "insects"] l.color = rgb(255, 255, 255) l.backgroundColor = rgb(100, 100, 100) f.inputs << l f = form(f) while 1 f.doEvents() ' Check for value of the active input field if (len(f.value) > 0) then at 0,0 print f.value; " " end if wend f.close() l.type = "choice" l.x = 120 l.y = 120 l.width = 100 l.value = "cats|dogs|fish|birds|insects" ' alternative way is to pass an array: ' l.value = ["cats", "dogs", "fish", "birds", "insects"] l.color = rgb(255, 255, 255) l.backgroundColor = rgb(100, 100, 100) f.inputs << l f = form(f) while 1 f.doEvents() ' Check for value of the active input field if (len(f.value) > 0) then at 0,0 print f.value; " " end if wend f.close() t.type = "text" t.x = 120 t.y = 120 t.width = 300 t.value = "Add more text" ' t.height = 100 ' if hight is not defined, single line field t.color = rgb(255, 255, 255) t.backgroundColor = rgb(100, 100, 100) t.length = 50 ' number of characters ' create additionally an OK-Button to update the form object ' otherwise the text field blocks loop b.type = "button" b.x = 120 + t.width + 10 b.y = 120 b.label = "OK" b.backgroundcolor = rgb(60, 60, 60) b.onclick = @OKButtonClicked f.inputs << t f.inputs << b f = form(f) while 1 f.doEvents() wend f.close() sub OKButtonClicked() f.refresh(1) ' Update the form object at 0,0 print f.inputs[0].value ' Text field is the first element added to the formMAP end In this example a callback function will be used. If you want to use the doEvents result instead, have a look at example 2.
' Create a simple button and save it as png ' If you have already an image for you button, ' this part is not necessary. circle 100,100,100 color 15 filled ButtonImage = image(0,0,200,200) ButtonImage.save("button.png") cls ' Define image button button.type = "image" button.name = "button.png" button.x = 120 button.y = 120 button.onclick = @ButtonClicked ' Callback function, definition see below. formMAP.inputs << button f = form(formMAP) while 1 f.doEvents() wend f.close() sub ButtonClicked() at 0,0 Clicked++ print "Button clicked " + Clicked + " times" end f.handleKeys = 0 ' create some buttons button1.y = 120 button1.label = "Button1" button1.value = "valueofButton1" button1.backgroundcolor = rgb(255,0,0) button1.onclick = @HelloWorld 'this prints on load button2.x = -1 button2.y = 120 button2.label = "Button2" button2.value = "valueofButton2" button3.value = "cats" button3.x = -1 button3.y = 120 button3.background = 223344 b4.type = "choice" b4.value = "cats|dogs|Fish|cats|dogs|Fish|cats|dogs|Fish|cats|dogs|Fish" b4.selectedIndex = 2 b4.x = -1 b4.y = 120 b5.type = "list" b5.value = "cats|dogs|Fish|cats|dogs|Fish|cats|dogs|Fish|cats|dogs|Fish|end|lol" b5.x = -1 b5.y = 120 b5.height = 120 b6.type = "text" b6.value = "cats" b6.length=30 b6.x = -1 b6.y = 120 b6.width = 50 b6.noFocus = 0 ' add buttons to the form f.inputs << button1 f.inputs << button2 f.inputs << button3 f.inputs << b4 f.inputs << b5 f.inputs << b6 f.backgroundcolor = "green" ' at this stage 'f' is just a plain user defined structure (map) ' after calling FORM, 'f' becomes a system form object with three special functions ' doEvents, close and refresh (see sokoban.bas for refresh) f = form(f) ' the string version of the form is JSON (see https://en.wikipedia.org/wiki/JSON) TSAVE "f.frm", f while 1 ' pump the system event queue f.doEvents() ' process the event in$ = inkey at 0,0 if len(in$)>1 then flag= asc(left(in$,1)) keychar =right(in$,1) n= asc(keychar) if (flag == 1) ? "Ctrl : ";keychar ; " " else if (flag == 2) ? "Alt : "; keychar else if (flag == 3) ? "Ctrl+Alt: "; keychar ; " " else ? "Arrow: "; n ; " " end if else vkey = asc(in$) if (vkey == 8) then ? "backspace!" else if (vkey == 127) then ? "delete !" else ? " key= "; in$; " "; vkey endif endif if b6.value <> "cats" then ? b6.value if (len(f.value) > 0) then print f.value; " " end if wend f.close() func HelloWorld ? "hello world" end 