FORM
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.
The form object
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. |
Defining the input fields
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. |
Change or read the GUI elements
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:
0].color = 12
f.inputs[0) f.refresh(
To get a list of all available elements of the n-th GUI element, you
can simply use print f.inputs[n]
.
Example 1: Creating a push button using callback function
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"
button.type = 120
button.x = 120
button.y = label = "Button"
button.rgb(60, 60, 60)
button.backgroundcolor = ' Callback function, definition see below
button.onclick = @ButtonClicked
formMAP.inputs << button
form(formMAP)
f =
while 1
ii++locate 0,0: print ii
delay(100)
wend
close()
f.
sub ButtonClicked()
locate 1,0
Clicked++print "Button clicked " + Clicked + " times"
end
Example 2: Creating a push button using doEvents result
"button"
button.type = 120
button.x = 120
button.y = label = "Button"
button.rgb(60, 60, 60)
button.backgroundcolor = 1 ' unique value to identify the button
button.value =
formMAP.inputs << button
form(formMAP)
f =
while 1
f.doEvents()if(f.value == 1) then
ii++at 0,0
print "Button cklicked " + ii + " times."
endif
wend
close() f.
Example 3: Creating a label
"label"
l.type = 120
l.x = 120
l.y = label = "Label"
l.color = rgb(255, 60, 60)
l.
f.inputs << l
form(f)
f =
while 1
f.doEvents()wend
close() f.
Example 4: Creating a link to an external website
"link"
l.type = 120
l.x = 120
l.y = label = "Link to SmallBASIC website"
l."https://smallbasic.github.io"
l.value = true
l.isExternal = color = rgb(100, 100, 255)
l.
f.inputs << l
form(f)
f =
while 1
f.doEvents()wend
close() f.
Example 5: Creating a listbox
"listbox"
l.type = 120
l.x = 120
l.y = 200
l.height = 100
l.width = "cats|dogs|fish|birds|insects"
l.value = ' alternative way is to pass an array:
' l.value = ["cats", "dogs", "fish", "birds", "insects"]
color = rgb(255, 255, 255)
l.rgb(100, 100, 100)
l.backgroundColor =
f.inputs << l
form(f)
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
close() f.
Example 6: Creating a dropdown listbox
"choice"
l.type = 120
l.x = 120
l.y = 100
l.width = "cats|dogs|fish|birds|insects"
l.value = ' alternative way is to pass an array:
' l.value = ["cats", "dogs", "fish", "birds", "insects"]
color = rgb(255, 255, 255)
l.rgb(100, 100, 100)
l.backgroundColor =
f.inputs << l
form(f)
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
close() f.
Example 7: Creating a text input field
"text"
t.type = 120
t.x = 120
t.y = 300
t.width = "Add more text"
t.value = ' t.height = 100 ' if hight is not defined, single line field
color = rgb(255, 255, 255)
t.rgb(100, 100, 100)
t.backgroundColor = 50 ' number of characters
t.length =
' create additionally an OK-Button to update the form object
' otherwise the text field blocks loop
"button"
b.type = 120 + t.width + 10
b.x = 120
b.y = label = "OK"
b.rgb(60, 60, 60)
b.backgroundcolor =
b.onclick = @OKButtonClicked
f.inputs << t
f.inputs << b
form(f)
f =
while 1
f.doEvents() wend
close()
f.
sub OKButtonClicked()
1) ' Update the form object
f.refresh(at 0,0
print f.inputs[0].value ' Text field is the first element added to the formMAP
end
Example 8: Image button using callback function
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
image(0,0,200,200)
ButtonImage = "button.png")
ButtonImage.save(cls
' Define image button
"image"
button.type = "button.png"
button.name = 120
button.x = 120
button.y = ' Callback function, definition see below.
button.onclick = @ButtonClicked
formMAP.inputs << button
form(formMAP)
f =
while 1
f.doEvents()wend
close()
f.
sub ButtonClicked()
at 0,0
Clicked++print "Button clicked " + Clicked + " times"
end
Example 9: One more example
0
f.handleKeys = ' create some buttons
120
button1.y = label = "Button1"
button1."valueofButton1"
button1.value = rgb(255,0,0)
button1.backgroundcolor = 'this prints on load
button1.onclick = @HelloWorld 1
button2.x = -120
button2.y = label = "Button2"
button2."valueofButton2"
button2.value = "cats"
button3.value = 1
button3.x = -120
button3.y = 223344
button3.background = "choice"
b4.type = "cats|dogs|Fish|cats|dogs|Fish|cats|dogs|Fish|cats|dogs|Fish"
b4.value = 2
b4.selectedIndex = 1
b4.x = -120
b4.y = "list"
b5.type = "cats|dogs|Fish|cats|dogs|Fish|cats|dogs|Fish|cats|dogs|Fish|end|lol"
b5.value = 1
b5.x = -120
b5.y = 120
b5.height = "text"
b6.type = "cats"
b6.value = 30
b6.length=1
b6.x = -120
b6.y = 50
b6.width = 0
b6.noFocus = ' add buttons to the form
f.inputs << button1
f.inputs << button2
f.inputs << button3
f.inputs << b4
f.inputs << b5
f.inputs << b6"green"
f.backgroundcolor = ' 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)
form(f)
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
inkey
in$ = at 0,0
if len(in$)>1 then
asc(left(in$,1))
flag= right(in$,1)
keychar =asc(keychar)
n= if (flag == 1)
"Ctrl : ";keychar ; " "
? else if (flag == 2)
"Alt : "; keychar
? else if (flag == 3)
"Ctrl+Alt: "; keychar ; " "
? else
"Arrow: "; n ; " "
? end if
else
asc(in$)
vkey = 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
close()
f.func HelloWorld
"hello world"
? end