Colored Character Forms for Euphoria

Contents Overview Example programs Coloring forms About ccf_displayform Library reference Known issues Acknowledgements The Authors

Overview

A brief description

Colored character forms for Euphoria is a simple cross platform method for building character form based applications. The functionality is provided via one include file (ccform.e) which contains a number of functions, procedures and global constants. By using these a basic character form can be created, with or without colors, and then the user can interact with the form.

An extra apicon.e include file is required because of the way the WIN32 console is operated. However, the file is not included by the library on platforms other than WIN32.

Using the library

Learning how to use colored character forms for Euphoria can be achieved by looking at example programs, running them and modifying them. At least, it's probably the right first step before looking at the exact specifications of a complete command set.

Example programs

Quick taster

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 colored character forms (but monochrome yet):

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 :-)

Note that there is no color here yet. This will have to wait for more basic topics being covered.

Example program "hello.ex"

Study the following Euphoria program:

-- -- hello.ex -- -- the classic hello world program using ccform.e (basic character forms) -- include ccform.e -- main code sequence ccf ccf_savescreen() --<--saves current text mode screen ccf = ccf_newform() --<--creates the data structure of a new form ccf = ccf_addtext(ccf, 1, 1, "Hello, World!") --<--displays some text at the specified position ccf = ccf_addtext(ccf, 3, 1, "Press one of the following keys to exit:") ccf = ccf_addtext(ccf, 5, 1, "F1, F2, F3, F4, F5, F6, F7 or F8") ccf = ccf_addfield(ccf, 7, 1, 0, "dummy", "") --<--creates an input field at the specified position ccf = ccf_interact(ccf) --<--displays the form and lets the user interact with it ccf_restorescreen() --<--restores whatever ccf_savescreen mught have saved 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.

A colored character form is stored in a sequence variable. The hello.ex program declares the ccf variable as a sequence.

Just in case something valuable was displayed on screen, or on the console in graphic mode, prior to running the program, you may wish to save the displayed screen contents. ccf_savescreen() does this if there appears to be something to save.

For your convenience, a related function, ccf_savescreenEx(), returns the screen size as a {rows,columns} sequence. This particular program does not need the hint, but others may.

Note that there is only one saved state at a given time. So, calling ccf_savescreen() destroys whatever had been saved beforehand.

The ccf variable is now initialised via a call to the ccf_newform() function.

The text content of the form is then built up by successive calls to the ccf_addtext function. The ccf_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. Note that they may be decimal numbers, in which case they are rounded down.

If the initiaal value lies between 0 and 1 excluded, then the line or column number is computed as a portion of screen. Thus, on a 43-line display, a value of 0.6 will be converted to 43*0.6=25.8, rounded down to 25.

Every colored 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. Adding fields is done by a call to the ccf_addfield function. The ccf_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 characters) 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 ccf_interact function is now called. At this point the character form is displayed on the screen and the user can interact with the form. There wiould have been more colors if commands like ccf_attributes had been added. 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 ccf_interact function remembers which function key was pressed. For the purpose of the hello.ex program which function key was pressed is not of interest so the program does not check for this data, although it can.

Next, the program restores the screen by calling ccf_restorescreen(). If there was something displayed in text mode when ccf_savescreen() was called, it is rendered back as wel as the current text attributes and cursor position. The console is closed whenever it makes sense to do so and nothing had been saved.

Example program "fkey.ex"

Study the following Euphoria program:

-- -- fkey.ex -- -- work out which function key was pressed on a basic character form -- include ccform.e -- main code sequence ccf integer fkey sequence fkeytext ccf = ccf_newform() ccf = ccf_addtext(ccf, 1, 1, "Press one of the following function keys:") for i = 1 to 8 do ccf = ccf_addtext(ccf, 2+i, 9, sprintf("F%d", {i})) end for ccf = ccf_addfield(ccf, 24, 1, 0, "dummy", "") ccf = ccf_interact(ccf) fkey = ccf_key(ccf) --<--retrieves the function key the user just hit if fkey = ccf_FKEY1 then --<--this identifies the F1 key fkeytext = "F1" elsif fkey = ccf_FKEY2 then fkeytext = "F2" elsif fkey = ccf_FKEY3 then fkeytext = "F3" elsif fkey = ccf_FKEY4 then fkeytext = "F4" elsif fkey = ccf_FKEY5 then fkeytext = "F5" elsif fkey = ccf_FKEY6 then fkeytext = "F6" elsif fkey = ccf_FKEY7 then fkeytext = "F7" elsif fkey = ccf_FKEY8 then fkeytext = "F8" else fkeytext = "*Unknown*" end if ccf = ccf_newform() ccf = ccf_addtext(ccf, 1, 1, sprintf("Function key %s was pressed.", {fkeytext})) ccf = ccf_addtext(ccf, 3, 1, "Now press one of:") for i = 1 to 8 do ccf = ccf_addtext(ccf, 4+i, 9, sprintf("F%d", {i})) end for ccf = ccf_addtext(ccf, 14, 1, "to exit.") ccf = ccf_addfield(ccf, 24, 1, 0, "dummy", "") ccf = ccf_interact(ccf) 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 ccf_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 ccform.e and made global:

ccf_FKEY1 ccf_FKEY2 ccf_FKEY3 ccf_FKEY4 ccf_FKEY5 ccf_FKEY6 ccf_FKEY7 ccf_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.

Example program "field.ex"

Study the following Euphoria program:

-- -- field.ex -- -- data input using basic character forms -- include ccform.e -- main code sequence ccf sequence name ccf = ccf_newform() ccf = ccf_addtext(ccf, 1, 1, "Please type your name:") ccf = ccf_addfield(ccf, 3, 1, 40, "name", "") ccf = ccf_addtext(ccf, 5, 1, "Press F1 to continue.") ccf = ccf_allowfkeys(ccf, "1") --<--defines which function keys are allowed ccf = ccf_interact(ccf) name = ccf_fieldread(ccf, "name") --<--retrieves data in named field ccf = ccf_newform() ccf = ccf_addtext(ccf, 1, 1, sprintf("Your name is \"%s\".", {name})) ccf = ccf_addtext(ccf, 3, 1, "Press F8 to exit.") ccf = ccf_addfield(ccf, 24, 1, 0, "dummy", "") ccf = ccf_allowfkeys(ccf, "8") ccf = ccf_interact(ccf) 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:

ccf_addfield ccf_fieldread ccf_allowfkeys

The ccf_addfield call specifies a field width of 40 characters. This sort of use is more typical than the one in the first example program. The input field displays as 40 underscore characters in a row, the line wrapping if need be. The cursor is placed at the first position in the first (here unique) field. Data can be typed in. By default, it is entered in insert mode (each typed characters pushes the ones on the right, so that it does not destroy anything). The Insert key toggles insertion mode between Insert and Overstrike. Once 40 characters are typed any extra inserted characters are ignored.

Characters are erased using the backspace key which removes the character immediately to the left of the cursor, or the delete key, which erases the character right under the cursor. It is also possible to erase a whole field using the ^K key, or alternatively Alt-Backspace..

The cursor can be moved within a field:

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.

On DOS and Windows, the left arrow, right arrow, home and end keys are available and perform the same tasks respectively.

The ccf_fieldread function extracts the data contained in a field. This is why when a field is added with the ccf_addfield function a name is specified. By using the same name in a call to ccf_fieldread the data can be extracted.

The ccf_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 ccf_allowfkeys the number of function keys can be reduced. For example:

ccf = ccf_allowfkeys(ccf, "18")

will only allow interaction with the colored character form to be ended by pressing F1 or F8.

Example program "password.ex"

Study the following Euphoria program:

-- -- password.ex -- -- how to hide sensitive field information -- include ccform.e -- main code sequence password sequence ccf password = "" while 1 do ccf = ccf_newform() ccf = ccf_addtext(ccf, 1, 1, "Password Demo") ccf = ccf_addtext(ccf, 2, 1, "^^^^^^^^^^^^^") ccf = ccf_addtext(ccf, 4, 1, "Password:") ccf = ccf_addfield_pw(ccf, 4, 11, 10, "password", password, '*') --<--creates a field where input characters will be masked ccf = ccf_addtext(ccf, 6, 1, "F1=Login") ccf = ccf_addtext_rj(ccf, 6, 20, "F8=Exit") --<--creates right justified text ccf = ccf_allowfkeys(ccf, "18") ccf = ccf_interact(ccf) password = ccf_fieldread(ccf, "password") if ccf_key(ccf) = ccf_FKEY1 then exit end if if ccf_key(ccf) = ccf_FKEY8 then clear_screen() abort(0) end if end while ccf = ccf_newform() ccf = ccf_addutext(ccf, 1, 1, "Login", '=') --<--displays underlined text ccf = ccf_addtext(ccf, 4, 1, sprintf("You will login using \"%s\" as your password.", {password})) ccf = ccf_addtext_rj(ccf, 6, 20, "F8=Exit") ccf = ccf_addfield(ccf, 7, 1, 0, "dummy", "") ccf = ccf_allowfkeys(ccf, "8") ccf = ccf_interact(ccf) clear_screen() abort(0) -- end of file

This program introduces a new function:

ccf_addfield_pw

This is similar to the ccf_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 ccf_addfield_pw.

Example program "navigate.ex"

Study the following Euphoria program:

-- -- navigate.ex -- -- a medium complexity basic character form -- include ccform.e -- main code integer nextstep, extratxt sequence fname sequence sname sequence email sequence password sequence ccf sequence d fname = "" sname = "" email = "" password = "" nextstep = 0, extratxt = 0 while 1 do ccf = ccf_newform() ccf = ccf_addutext(ccf, 1, 1, "Personal Details", '=') d = date() ccf = ccf_addtext_rj(ccf, 1, 80, sprintf("Time --- %02d:%02d:%02d", {d[4], d[5], d[6]})) ccf = ccf_addtext(ccf, 4, 1, "First name:") ccf = ccf_addfield(ccf, 4, 20, 40, "fname", fname) ccf = ccf_addtext(ccf, 5, 1, "Surname:") ccf = ccf_add_tag(ccf, "sname") --<--assigns a name to a text label ccf = ccf_addfield(ccf, 5, 20, 40, "sname", sname) ccf_attributes(BLUE+16*RED, YELLOW*16) --<--defines different attributes for labels and input fields ccf = ccf_addtext(ccf, 6, 1, "Email address:") ccf = ccf_addfield(ccf, 6, 20, 40, "email", email) ccf = ccf_addtext(ccf, 7, 1, "Password:") ccf = ccf_addfield_pw(ccf, 7, 20, 40, "password", password, '*') ccf_attribute(16*LIGHT_CYAN) --<--sets label and field attribute to the same value ccf = ccf_addutext(ccf, 22, 1, "F1=Continue", '-') ccf = ccf_addutext(ccf, 22, 35, "F2=Reset", '-') ccf = ccf_addutext_rj(ccf, 22, 80, "F8=Exit", '-') --<--creates a right justified label ccf_attribute(16*WHITE) ccf = ccf_allowfkeys(ccf, "128") while 1 do while 1 do ccf = ccf_interact(ccf) fname = ccf_fieldread(ccf, "fname") sname = ccf_fieldread(ccf, "sname") email = ccf_fieldread(ccf, "email") password = ccf_fieldread(ccf, "password") if ccf_key(ccf) = CCF_FKEY1 then if length(email)=0 or length(password)=0 or (length(sname)=0 and extratxt) then ccf = ccf_change_attributes( ccf, "sname", BLUE+16*RED, YELLOW*16) --<--changes text and field attributes for items with a given name if extratxt = 0 then ccf = ccf_addtext( ccf, 2, 10, "EXTRA details required now !") extratxt = 1 end if else nextstep = 1 end if exit end if if ccf_key(ccf) = CCF_FKEY1 then exit end if if ccf_key(ccf) = CCF_FKEY2 then fname = "" sname = "" email = "" password = "" end if if ccf_key(ccf) = CCF_FKEY8 then clear_screen() abort(0) end if end while if nextstep then exit end if end while if nextstep then exit end if end while ccf = ccf_newform() ccf = ccf_addtext(ccf, 1, 1, sprintf("Your first name is \"%s\".", {fname})) ccf = ccf_addtext(ccf, 2, 1, sprintf("Your surname is \"%s\".", {sname})) ccf = ccf_addtext(ccf, 3, 1, sprintf("Your email address is \"%s\".", {email})) ccf = ccf_addtext(ccf, 4, 1, sprintf("Your password is \"%s\".", {password})) ccf = ccf_addtext(ccf, 6, 1, "Press F8 to exit.") ccf = ccf_addfield(ccf, 24, 1, 0, "dummy", "") ccf = ccf_allowfkeys(ccf, "8") ccf = ccf_interact(ccf) clear_screen() abort(0) -- end of file

This program shows many of the features currently available in basic character forms for Euphoria. It also illustrates how to add colors to a form. 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.

You'll notice that it bitterly complains if one of the markedly mandatory fields is not filled in.

There are three new formatting functions introduced in this example:

ccf_addtext_rj ccf_addutext ccf_addutext_rj

The ccf_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:

ccf = ccf_addtext_rj(ccf, 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 ccf_addutext adds text in a simular way to ccf_addtext but the text is then "underlined" by adding the character specified in argument number five beneath each character of text. For example:

ccf = ccf_addutext(ccf, 1, 1, "Main Menu", '=')

would result in a form which had the following:

Main Menu =========

in the top left corner of the screen.

The ccf_addutext_rj function combines the effects of ccf_addutext and ccf_addtext_rj. Text is right justified and "underlined" with the character specified as argument number five.

Last but not least: coloring forms.

The ccf_attribute function takes one argument, an attribute number. Attribute numbers are formed as laid out in the graphics.e standard Euphoria include file. Both the text and entry attributes are set to the new value.

The internal variables this function sets are common to all forms. When changing attributes, the change applies to any text or field entry subsequently defined, until, of course, another change is made.

The ccf_attributes function takes two attribute number as arguments. The first one is the text attribute, the second one is the field atrribute.

Two other functions were not involved in the above program: ccf_text_attribute and ccf_field_attribute. Both take an attribute number as argument. They respectively and separately set the text and field atribute.

The initial value of both attributes is determined by reading the system configuration. If this fails, for instance because no console window is open at the time ccform.e is included, conservative white on black is assumed.

You can change the color of a text or field entry after it was displayed, so that the changes applies next time you display the form again. This is done by the ccf_change_attributes function. It takes four arguments:

The sequence to which changes apply;
The name of the entry (see below);
Two attribute values, as for the ccf_attributes function.

There is a ccf_change_attribute function too, which takes one argument less and uses the only attribute passed to it for both text and field attributes.

What is to be passed as second argument to both functions? For fields, use the name of the field. For text items, there must be some way to assign a neme to them.

The way is the ccf_add_tag function. It takes a string (sequence of atoms) as sole argument, and tags the last item defined by ccf_addtext or its friends. The entry name is this tag for text items.

Using a field name as a tag, like in the above program, allows to affect both items. Using a tag which is not a field entry will only affect the tagged item. And using a fild name that is not a tag affects only the field.

Tags are not unique identifiers, so that you can affect several text items at a time.

The ccf_displayform function

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 ccf_displayform function to display it. The ccf_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 ccf_displayform function to display a text based progress bar:

-- -- progress.ex -- -- a crude example of a text based progress bar -- include misc.e include ccform.e -- main code sequence ccf sequence ccf2 sequence bar while 1 do ccf = ccf_newform() ccf = ccf_addutext(ccf, 5, 35, "Progress Bar", '=') ccf = ccf_addtext(ccf, 22, 1, "F1=Show Progress") ccf = ccf_addtext_rj(ccf, 22, 80, "F8=Exit") ccf = ccf_addfield(ccf, 23, 1, 0, "dummy", "") ccf = ccf_allowfkeys(ccf, "18") ccf = ccf_interact(ccf) if ccf_key(ccf) = ccf_FKEY1 then clear_screen() for i = 1 to 100 do ccf2 = ccf_newform() ccf2 = ccf_addtext(ccf2, 8, 34, "Please Wait") ccf2 = ccf_addtext(ccf2, 10, 38, sprintf("%d%%", {i})) bar = repeat('#', i/2) ccf2 = ccf_addtext(ccf2, 12, 16, bar) ccf_displayform(ccf2, 0) --<--draws the forms without user interaction sleep(1) end for end if if ccf_key(ccf) = ccf_FKEY8 then clear_screen() abort(0) end if end while -- end of file

The ccf_displayform was originally an internal function used by the ccf_interact function. It was an after thought to make it globally accessible.

Library reference

Here are gathered documentation information about all the symbols made available by ccform.e:

Initialisation and cleanup

Procedure ccf_savescreen

Syntax: ccf_savescreen()

Description

Checks if a text console is opened in graphic mode, and checks if the available text screen is empty. Opens the console if needed and saves current video attributes, screen data and cursor position.

Arguments: none.

Function ccf_savescreenEx

Syntax: s=ccf_savescreenEx()

Description

Performs ccf_savescreen() as above and returns the screen size.

Arguments: none.

Return value:

A pair {rows,columns} showing the dimensions of the text screen.

Procedure ccf_restorescreen

Syntax: ccf_restorescreen()

Description:

If the screen had some contents saved by ccf_savescreen(), they are restored. Otherwise, the console is closed if applicable.

Arguments: None.

Function ccf_newform

Syntax: form2=ccf_newform()

Description: returns a sequence ready to receive form data. This new form does not have any text or input field in it.

Return value: A sequence which can grow by adding items toit using the appropriate specialised functions.

Displaying the contents of an existing form

Procedure ccf_displayform

Syntax: ccf_displayform(sequence form,integer cls_flag)

Description: Displays the form form, optionally clearing the screen before.

Arguments:

form is the variable holding the form to display. cls_flag is 0 to prevent a preliminary clear_screen(), or 1 to allow it.

Function ccf_interact

Syntax: form2=ccf_interact(sequence form)

Description: Displays the form form, and lets the user enter data in it. Function keys F1 to F8 (or Esc-1 to Esc-8) are monitored. The procedure returns when the user hits an allowed function key.

Arguments: form is the variable holding the form to display.

Return value: The modified form.

Building a form.

Adding text entries

Function ccf_addtext

Syntax: ccf_addtext(sequence form,atom line,atom column,sequence text)

Description:

Creates a label at the 1-based screen location defined by {line,column} in the form form, using the text text, left-justified. line and column are rounded down if not less than 1.

If line or column is between 0 and 1 excluded, the value is multiplied by the relevant screen dimension before rounding.

Return value:

The modified form.

Function ccf_addtext_rj

Syntax: ccf_addtext_rj(sequence form,atom line,atom column,sequence text)

Description:

Creates a label at the 1-based screen location defined by {line,column} in the form form, using the text text, right-justified. line and column are rounded down if not less than 1.

If line or column is between 0 and 1 excluded, the value is multiplied by the relevant screen dimension before rounding.

Return value:

The modified form.

Function ccf_addutext

Syntax: ccf_addutext(sequence form,atom line,atom column,sequence text)

Description:

Creates a label at the 1-based screen location defined by {line,column} in the form form, using the text text, left-justified. line and column are rounded down if not less than 1. The text is then underlined using the uchar character, common values of which are '-', '=' or '*'.

If line or column is between 0 and 1 excluded, the value is multiplied by the relevant screen dimension before rounding.

Return value:

The modified form.

Function ccf_addutext_rj

Syntax: ccf_addutext_rj(sequence form,atom line,atom column,sequence text)

Description:

Creates a label at the 1-based screen location defined by {line,column} in the form form, using the text text, right-justified. line and column are rounded down if not less than 1. The text is then underlined using the uchar character, common values of which are '-', '=' or '*'.

If line or column is between 0 and 1 excluded, the value is multiplied by the relevant screen dimension before rounding.

Return value:

The modified form.

Adding field entries

Function ccf_addfield

Syntax: form2=ccf_addfield(sequence form,atom line,atom column,atom width,sequence name,sequence value)

Description:

Creates, at display time, an input field width character long at position {line,column} in form. The input fieldwraps to the line(s) below as needed. width may not be an integer, in which case it is processed just like line or column are.

The field has a name, which allows retrieving its value, and an initial value, which may be the empty string.

A field declared of length 0 and initial value "" is hidden.

Return value: The modified form.

Function ccf_addfield_pw

Syntax: form2=ccf_addfield_pw(sequence form,atom line,atom column,atom width,sequence name,sequence value,integer pwchar)

Description:

The field has a name, which allows retrieving its value, and an initial value, which may be the empty string.

Each character input in this field will display as the pwchar character. * is a fairly common value for pwchar.

A field declared of length 0 and initial value "" is hidden.

Return value: The modified form.

Setting colors

Procedure ccf_attributes

Syntax: ccf_attributes(integer text_attr,integer field_attr)

Description: Sets to text_attr the video attribute for any text entry to be added, and to field_attr the video attribute for any field entry to be added. The new values remain in force untill they are changed.

See graphics.e for a description of video attributes.

Procedure ccf_attribute

Syntax: ccf_attribute(integer new_attr,)

Description: Sets to new_attr the video attribute for any text or field entry to be added. The new value remain in force untill it is changed.

See graphics.e for a description of video attributes.

Procedure ccf_text_attribute

Syntax: ccf_text_attribute(integer text_attr,)

Description: Sets to text_attr the video attribute for any text entry to be added. The new value remain in force untill it is changed.

See graphics.e for a description of video attributes.

Procedure ccf_fiel_attribute

Syntax: ccf_attribute(integer field_attr,)

Description: Sets to field_attr the video attribute for any text or field entry to be added. The new value remain in force untill they are changed.

See graphics.e for a description of video attributes.

Getting and filtering input

Constant CCF_FKEYn

Description: n is an integer between 1 and 8 included. CCF_FKEYn represents the Fn function key, also known as Esc-n.

Function ccf_allowfkeys

Syntax: form2=ccf_allowfkeys(sequence form,sequence keys)

Arguments: form is the form to affect, and keys is a sequence made of 0 or more digits between 1 and 8 included.

Description: Restricts the allowable function leys for form to those listed in keys. ccf_interact(form) will return only on an allowable function key being pressed.

Return value: The modified form

Function ccf_key

Syntax: key=ccf_key(sequence form)

Description: returns the value of the function key last used to end a form interaction.

Return value: One of the CCF_FKEYn constants.

Function ccf_fieldread

Syntax: value=ccf_fieldread(sequence form,sequence name)

Description: Fetches the value entered in the field name of form form, and returns it as a string.

Return value: the text input in designated field.

Miscellaneous

Function ccf_add_tag

Syntax: form2=ccf_add_tag(sequence form,sequence tag)

Description: Assigns the name tag to the last text label defined in form.

Return value: The modified form.

Function ccf_change_attributes

Syntax: ccf_change_attributes(sequence form,sequence name,integer text_attr,integer field_attr)

Description: Changes the video attribute of any text entry tagged name to text_attr, and changes the video attribute of field name to field_attr. The changes will become effective next time form is displayed.

Return value: The modified form.

Function ccf_change_attribute

Syntax: ccf_change_attributes(sequence form,sequence name,integer new_attr)

Description: Changes the video attribute of any text entry tagged name to new_attr, as well as the video attribute of field name. The changes will become effective next time form is displayed.

Return value: The modified form.

Known issues

Q: The grey Enter key may not work, while the main (bigger) Enter key does.

A: That's not the library's fault. Windows does report the grey Enter key correctly, while DOS32 does not. If you encounter the problem with a .ex file, try running it as a .e or .exw file, and the grey Enter key will operate again as expected.

Q: Can older programs using bcform.e be run by just changing bcform to ccform? It would be cool...

A: This holds true from version 1.17 onward. All bcf_ calls are wrapped to their ccf_ counterparts.

Q: Why did the older bcform.e require inclusion of get.e and dll.e?

A: Possibly to avoid distributing them. As they are stanndard files, ccform.e includes them for you, so that you need no longer bother.

Acknowledgements

The original author got the idea for colored 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 Authors

The author of basic character forms for Euphoria, on which this library is based, is Andy Cranston <andy@systemzone.freeserve.co.uk>. Colors, decimal positioning and some extra editing functions were added by Christian Cuvier <ccuvier@free.fr>.

Last updated November 2nd, 2004.