Basic character forms for Euphoria is a simple cross platform method for building character form based applications. The functionality is provided via one include file (bcform.e) which contains a number of functions, procedures and global constants. By using these a basic character form can be created and then the user can interact with the form.
Here is an example screen shot of a simple call tracking system (these are also know as helpdesk or trouble ticket systems) coded in Euphoria using basic character forms:
Display/Edit/Close Existing Call Call ID 0191-2
-------------------------------- --------------
Contact name: Fred Bloggs_________________________________________________
Company: Acme Systems________________________________________________
Phone: 0123 456 789________________________________________________
Mobile: 0770 777 777________________________________________________
FAX: ____________________________________________________________
Email: fred.bloggs@acme.com________________________________________
Opened: 10-July-2002 12:29:16
Opened by: joe
Closed:
Closed by:
Description:
The L1000 returned from Acme Systems has a damaged memory board.______________
Fred needs to advise on whether to fix, upgrade or scrap._____________________
Also a power supply returned from Acme needs to be tested and returned to_____
stock.________________________________________________________________________
______________________________________________________________________________
F1=Update Call F2=Comments F3=Close Call F4=Print Call F8=Back
The names and numbers have been changed to protect the innocent :-)
The best way to learn how to use basic character forms for Euphoria is to look at example programs, run them and modify them.
Study the following Euphoria program:
--
-- hello.ex
--
-- the classic hello world program using bcform.e (basic character forms)
--
include get.e
include dll.e
include bcform.e
-- main code
sequence bcf
bcf = bcf_newform()
bcf = bcf_addtext(bcf, 1, 1, "Hello, World!")
bcf = bcf_addtext(bcf, 3, 1, "Press one of the following keys to exit:")
bcf = bcf_addtext(bcf, 5, 1, "F1, F2, F3, F4, F5, F6, F7 or F8")
bcf = bcf_addfield(bcf, 7, 1, 0, "dummy", "")
bcf = bcf_interact(bcf)
clear_screen()
abort(0)
-- end of file
This program displays the "Hello, World!" message on the screen. Also displayed is a message advising to press a function key (F1 through F8) to exit the program. Note that if you are running on Linux you need to press the Escape key followed by a numeric digit 1 through 8 to get the effect of a function key press. For example, to get the effect of pressing F4 you press Escape and then 4.
The program structure can now be examined more closely.
The bcform.e include requires that the standard get.e and dll.e includes that are part of the Euphoria distribution are included before bcform.e is included.
A basic character form is stored in a sequence variable. The hello.ex program declares the bcf variable as a sequence.
The bcf variable is initialised via a call to the bcf_newform() function.
The text content of the form is now built up by successive calls to the bcf_addtext function. The bcf_addtext function takes four arguments:
The variable containing the form
The line number the text is to appear on
The column number the text is to start from
The text itself
Line and column numbers start at 1 with line 1 and column 1 being the top left position on the screen.
Every basic character form requires at least one data field. For the form in the hello.ex program which simply displays data and does not require any data input a dummy field is added with a call to the bcf_addfield function. The bcf_addfield function takes six arguments:
The variable containing the form
The line number the field is to appear on
The column number the field is to start from
The length (in charactets) of the field
A name for the field so it's value can be retrieved later on
An initial value for the field
Specifying a field length of 0 and a null string for the initial value makes the field "hidden".
The bcf_interact function is now called. At this point the basic character form is displayed on the screen and the user can interact with the form. Because the form in hello.ex is very simple the only interaction possible from the user is pressing one of the eight function keys F1 through F8.
When one of the eight function keys F1 through F8 is pressed the bcf_interact function remembers which function key was pressed and then exits. For the purpose of the hello.ex program which function key was pressed is not of interest so the program now exits.
Study the following Euphoria program:
--
-- fkey.ex
--
-- work out which function key was pressed on a basic character form
--
include get.e
include dll.e
include bcform.e
-- main code
sequence bcf
integer fkey
sequence fkeytext
bcf = bcf_newform()
bcf = bcf_addtext(bcf, 1, 1, "Press one of the following function keys:")
for i = 1 to 8 do
bcf = bcf_addtext(bcf, 2+i, 9, sprintf("F%d", {i}))
end for
bcf = bcf_addfield(bcf, 24, 1, 0, "dummy", "")
bcf = bcf_interact(bcf)
fkey = bcf_key(bcf)
if fkey = BCF_FKEY1 then
fkeytext = "F1"
elsif fkey = BCF_FKEY2 then
fkeytext = "F2"
elsif fkey = BCF_FKEY3 then
fkeytext = "F3"
elsif fkey = BCF_FKEY4 then
fkeytext = "F4"
elsif fkey = BCF_FKEY5 then
fkeytext = "F5"
elsif fkey = BCF_FKEY6 then
fkeytext = "F6"
elsif fkey = BCF_FKEY7 then
fkeytext = "F7"
elsif fkey = BCF_FKEY8 then
fkeytext = "F8"
else
fkeytext = "*Unknown*"
end if
bcf = bcf_newform()
bcf = bcf_addtext(bcf, 1, 1, sprintf("Function key %s was pressed.", {fkeytext}))
bcf = bcf_addtext(bcf, 3, 1, "Now press one of:")
for i = 1 to 8 do
bcf = bcf_addtext(bcf, 4+i, 9, sprintf("F%d", {i}))
end for
bcf = bcf_addtext(bcf, 14, 1, "to exit.")
bcf = bcf_addfield(bcf, 24, 1, 0, "dummy", "")
bcf = bcf_interact(bcf)
clear_screen()
abort(0)
-- end of file
The fkey.ex program displays one form which prompts the user to press one of the function keys F1 though F8 (note the use of a for loop to build the function key names) and displays a second form which indicates which function key was pressed on the first form.
The bcf_key function returns an integer which represents which function key was pressed. To avoid putting numbers into Euphoria code the following constants are defined in bcform.e and made global:
BCF_FKEY1
BCF_FKEY2
BCF_FKEY3
BCF_FKEY4
BCF_FKEY5
BCF_FKEY6
BCF_FKEY7
BCF_FKEY8
Because it is possible to determine which function key was pressed whilst a user was interacting with a form different actions can be taken. If a user pressed F1 then a customer record could be updated, if F2 was pressed some help text could be displayed and so on.
Study the following Euphoria program:
--
-- field.ex
--
-- data input using basic character forms
--
include get.e
include dll.e
include bcform.e
-- main code
sequence bcf
sequence name
bcf = bcf_newform()
bcf = bcf_addtext(bcf, 1, 1, "Please type your name:")
bcf = bcf_addfield(bcf, 3, 1, 40, "name", "")
bcf = bcf_addtext(bcf, 5, 1, "Press F1 to continue.")
bcf = bcf_allowfkeys(bcf, "1")
bcf = bcf_interact(bcf)
name = bcf_fieldread(bcf, "name")
bcf = bcf_newform()
bcf = bcf_addtext(bcf, 1, 1, sprintf("Your name is \"%s\".", {name}))
bcf = bcf_addtext(bcf, 3, 1, "Press F8 to exit.")
bcf = bcf_addfield(bcf, 24, 1, 0, "dummy", "")
bcf = bcf_allowfkeys(bcf, "8")
bcf = bcf_interact(bcf)
clear_screen()
abort(0)
-- end of file
This program displays a form with a single data field. Type in some data and then press F1. A second form will then be displayed showing the data that was typed in.
The points of interest are the following functions:
bcf_addfield
bcf_fieldread
bcf_allowfkeys
The bcf_addfield call specifies a field width of 40 characters. When displayed 40 underscore characters (_) are displayed. Because the form has only one field the cursor is placed in the field. Data can be typed. Once 40 characters are typed any extra characters are ignored. Characters are erased using the backspace key which removes the character immediately to the left of the cursor.
The cursor can be moved within a field:
On DOS and Windows use the left arrow, right arrow, home and end keys.
On Linux/FreeBSD use ^B to move left (back), ^F to move right (forward), ^A to move to the start of the field and ^E to move to the end of the field.
The bcf_fieldread function extracts the data contained in a field. This is why when a field is added with the bcf_addfield function a name is specified. By using the same name in a call to bcf_fieldread the data can be extracted.
The bcf_allowfkeys function restricts which function keys can be pressed to end the interaction with a form. The default setting is to allow any of the eight function keys F1, F2, F3, F4, F5, F6, F7 or F8. By calling bcf_allowfkeys the number of function keys can be reduced. For example:
bcf = bcf_allowfkeys(bcf, "18")
will only allow interaction with the basic character form to be ended by pressing F1 or F8.
Study the following Euphoria program:
--
-- password.ex
--
-- how to hide sensitive field information
--
include get.e
include dll.e
include bcform.e
-- main code
sequence password
sequence bcf
password = ""
while 1 do
bcf = bcf_newform()
bcf = bcf_addtext(bcf, 1, 1, "Password Demo")
bcf = bcf_addtext(bcf, 2, 1, "^^^^^^^^^^^^^")
bcf = bcf_addtext(bcf, 4, 1, "Password:")
bcf = bcf_addfield_pw(bcf, 4, 11, 10, "password", password, '*')
bcf = bcf_addtext(bcf, 6, 1, "F1=Login")
bcf = bcf_addtext_rj(bcf, 6, 20, "F8=Exit")
bcf = bcf_allowfkeys(bcf, "18")
bcf = bcf_interact(bcf)
password = bcf_fieldread(bcf, "password")
if bcf_key(bcf) = BCF_FKEY1 then
exit
end if
if bcf_key(bcf) = BCF_FKEY8 then
clear_screen()
abort(0)
end if
end while
bcf = bcf_newform()
bcf = bcf_addutext(bcf, 1, 1, "Login", '=')
bcf = bcf_addtext(bcf, 4, 1, sprintf("You will login using \"%s\" as your password.", {password}))
bcf = bcf_addtext_rj(bcf, 6, 20, "F8=Exit")
bcf = bcf_addfield(bcf, 7, 1, 0, "dummy", "")
bcf = bcf_allowfkeys(bcf, "8")
bcf = bcf_interact(bcf)
clear_screen()
abort(0)
-- end of file
This program introduces a new function:
bdf_addfield_pw
This is similar to the bcf_addfield function but an extra argument is supplied. This extra argument is a character to use to display data in the field instead of the actual user data typed. The main use is to hide the data from prying eyes so fields containing passwords and other sensitive information will benefit from bcf_addfield_pw.
Study the following Euphoria program:
--
-- navigate.ex
--
-- a medium complexity basic character form
--
include get.e
include dll.e
include bcform.e
-- main code
sequence fname
sequence sname
sequence email
sequence password
sequence bcf
sequence d
fname = ""
sname = ""
email = ""
password = ""
while 1 do
bcf = bcf_newform()
bcf = bcf_addutext(bcf, 1, 1, "Personal Details", '=')
d = date()
bcf = bcf_addtext_rj(bcf, 1, 80, sprintf("Time --- %02d:%02d:%02d", {d[4], d[5], d[6]}))
bcf = bcf_addtext(bcf, 4, 1, "First name:")
bcf = bcf_addfield(bcf, 4, 20, 40, "fname", fname)
bcf = bcf_addtext(bcf, 5, 1, "Surname:")
bcf = bcf_addfield(bcf, 5, 20, 40, "sname", sname)
bcf = bcf_addtext(bcf, 6, 1, "Email address:")
bcf = bcf_addfield(bcf, 6, 20, 40, "email", email)
bcf = bcf_addtext(bcf, 7, 1, "Password:")
bcf = bcf_addfield_pw(bcf, 7, 20, 40, "password", password, '*')
bcf = bcf_addutext(bcf, 22, 1, "F1=Continue", '-')
bcf = bcf_addutext(bcf, 22, 35, "F2=Reset", '-')
bcf = bcf_addutext_rj(bcf, 22, 80, "F8=Exit", '-')
bcf = bcf_allowfkeys(bcf, "128")
bcf = bcf_interact(bcf)
fname = bcf_fieldread(bcf, "fname")
sname = bcf_fieldread(bcf, "sname")
email = bcf_fieldread(bcf, "email")
password = bcf_fieldread(bcf, "password")
if bcf_key(bcf) = BCF_FKEY1 then
exit
end if
if bcf_key(bcf) = BCF_FKEY2 then
fname = ""
sname = ""
email = ""
password = ""
end if
if bcf_key(bcf) = BCF_FKEY8 then
clear_screen()
abort(0)
end if
end while
bcf = bcf_newform()
bcf = bcf_addtext(bcf, 1, 1, sprintf("Your first name is \"%s\".", {fname}))
bcf = bcf_addtext(bcf, 2, 1, sprintf("Your surname is \"%s\".", {sname}))
bcf = bcf_addtext(bcf, 3, 1, sprintf("Your email address is \"%s\".", {email}))
bcf = bcf_addtext(bcf, 4, 1, sprintf("Your password is \"%s\".", {password}))
bcf = bcf_addtext(bcf, 6, 1, "Press F8 to exit.")
bcf = bcf_addfield(bcf, 24, 1, 0, "dummy", "")
bcf = bcf_allowfkeys(bcf, "8")
bcf = bcf_interact(bcf)
clear_screen()
abort(0)
-- end of file
This program shows many of the features currently available in basic character forms for Euphoria. A form with four fields is displayed. To move to the next field press the Return key or the Tab key. To move to the previous field press the Escape key followed by the Tab key.
There are three new functions introduced in this example:
bcf_addtext_rj
bcf_addutext
bcf_addutext_rj
The bcf_addtext_rj function adds text to a form in the same way as bdf_addtext but the text is right justified to the column so:
bcf = bcf_addtext_rj(bcf, 1, 80, "Help")
adds the text "Help" to the top right of the screen. The "p" in "Help" will occupy column 80 on line 1.
The bcf_addutext adds text in a simular way to bcf_addtext but the text is then "underlined" by adding the character specified in argument number five beneath each character of text. For example:
bcf = bcf_addutext(bcf, 1, 1, "Main Menu", '=')
would result in a form which had the following:
Main Menu
=========
in the top left corner of the screen.
The bcf_addutext_rj function combines the effects of bcf_addutext and bcf_addtext_rj. Text is right justified and "underlined" with the character specified as argument number five.
It can be useful to just display a form without any user interaction. Build the form up in the usual way and then use the bcf_displayform function to display it. The bcf_displayform function takes two parameters:
The variable containing the form
An integer flag for clearing the screen
If the integer flag is 0 then the screen is not cleared. This can allow "smoother" display if forms are being displayed in quick succession. If the integer flag is 1 then the screen is cleared.
The following example Euphoria program shows a crude use of the bcf_displayform function to display a text based progress bar:
--
-- progress.ex
--
-- a crude example of a text based progress bar
--
include get.e
include dll.e
include misc.e
include bcform.e
-- main code
sequence bcf
sequence bcf2
sequence bar
while 1 do
bcf = bcf_newform()
bcf = bcf_addutext(bcf, 5, 35, "Progress Bar", '=')
bcf = bcf_addtext(bcf, 22, 1, "F1=Show Progress")
bcf = bcf_addtext_rj(bcf, 22, 80, "F8=Exit")
bcf = bcf_addfield(bcf, 23, 1, 0, "dummy", "")
bcf = bcf_allowfkeys(bcf, "18")
bcf = bcf_interact(bcf)
if bcf_key(bcf) = BCF_FKEY1 then
clear_screen()
for i = 1 to 100 do
bcf2 = bcf_newform()
bcf2 = bcf_addtext(bcf2, 8, 34, "Please Wait")
bcf2 = bcf_addtext(bcf2, 10, 38, sprintf("%d%%", {i}))
bar = repeat('#', i/2)
bcf2 = bcf_addtext(bcf2, 12, 16, bar)
bcf_displayform(bcf2, 0)
sleep(1)
end for
end if
if bcf_key(bcf) = BCF_FKEY8 then
clear_screen()
abort(0)
end if
end while
-- end of file
The bcf_displayform was originally an internal function used by the bcf_interact function. It was an after thought to make it globally accessible.
I got the idea for basic character forms for Euphoria from a combination of two sources. The first is the character interface used by many programs on the HP-UX UNIX operating system via the 700/96 character terminal. The second was Irv Mullins' GUI for DOS.
The author of basic character forms for Euphoria is Andy Cranston.
Last updated 15 March 2003.