Category : C Source Code
Archive   : TCU_31.ZIP
Filename : TCU.DOC

 
Output of file : TCU.DOC contained in archive : TCU_31.ZIP


Turbo-C Utilities - TCU 3.1
===========================


Foreword
--------

Suggestions, comments and complaints (hopefully not the latter!) will be
accepted electronically to:

Karl Keyte
European Space Operations Centre
Robert-Bosch Strasse 5
D-6100 Darmstadt
West Germany

Voice : +(49) 6151 902041 (Business)
+(49) 6150 2499 (Private)
e-Mail : [email protected]
Bix : kkeyte

All memory models other than TINY (which is not supported) are supplied with
this version. Compilations with ALL memory models MUST use the WORD ALIGN
option or else the programs WILL NOT WORK.

If you use the TCU package, please register with me by simply contacting me
on the e-Mail address above. This way I know who to contact when a new
release is available.




Disclaimer
----------

No responsibility taken for anything which may result from using the TCU
package. If anything unusual does result, please contact me on the above
e-Mail address with full details.


Introduction
------------

TCU is a library for Turbo-C v2.0 or Turbo-C++ v1.0 to provide a number of
services relating to menus, prompt and notice windows and form entry. This
document offers a full description of each of the services, their syntax
and operation. The following text describes each section briefly. It is up
to the user to write full test and application programs to demonstrate fully
the use of each.


Menus
-----

The TCU menu system offers pop-up menus and pulldown menus. Pulldown menus
utilise normal pop-up menus for each of the choices. A pop-up menu is
defined with the 'define_menu' service, displayed with 'display_menu' and
a choice is selected with 'read_menu_selection'. The menu is removed from
the screen with 'remove_menu'. Each menu should be declared in the calling
program as type MENU before being defined.

A pulldown menu is a set of title options, and each option may have an
associated pop-up menu which will be displayed beneath the pulldown option
when selected.

Items in pop-up menus may be set as 'unavailable', making that option non
selectable. This option may be toggled on and off.


Prompts and Notices
-------------------

A notice is a set of lines of text which is displayed in a notice window.
The notice must be cleared from the screen by the user pressing the RETURN
key. A notice is initiated with the 'prepare_notice' service, and each line
of text is added to the notice using 'notice_text'. When the notice has been
fully built it may be displayed with 'display_notice'. When it is no longer
needed, or a new notice is to be prepared, it should be cleared with the
'clear_notice' service.

A prompt is simply a notice with a single input field. The input field is
defined (in colour and size) with the 'prompt_input' service. As soon as
a call to 'prompt_input' is made, the notice becomes a prompt. This call
must be made prior to the call to 'display_notice'. A prompt is completed
by the user entering the prompt field and pressing the RETURN key.


Forms
-----

The forms package is a complete form entry system allowing fixed text and
variable input areas to be defined in a form. The attributes of the form
are written in a CUF ('C' Utilities Form) file and compiled into an object
form (CFO - 'C' Form Object) using the provided Forms Compiler. The compiler


checks the syntax and validity of each of the entries in the form source
file, and if no errors are found the object is generated. This object may
then be loaded by an application using the 'load_form' service. This gives
applications the flexibility not to depend on the exact form content which
may be modified without having to recompile or link any code (unless major
changes are made to the form structure).

Full details of the form source syntax are available in the Forms Compiler
documentation.

Each field in a form is addressed by its 'form id' number, which is not
specified in the form source, but is assigned at run-time. In order to
allow applications to refer to known fields, fields may be given a name
which may be used with the 'get_field_id' service to obtain the applicable
form id.

Fields may be one of 7 types, or 6 basic types:

Numeric - 2 types, 1 integer and 1 floating point.
String - Character strings
Date - Dates in US or European format
Logical - True/False, Yes/No, etc.
Choice - Enumerated selection types
Button - Selection buttons

Fixed text within a form is declared as TEXT rather than FIELD.

Each field or text item may be assigned a colour attribute, defining its
foreground and background colours. The COLOUR and INPUT keywords may be
used to assign default colour attributes for items not having a specific
colour attribute; this is the normal case.

Many operations exist with the services provided to change attributes and
behaviour of the fields. These are described fully in the following text.

Note that in the interest of retaining as much available dynamic memory as
possible for the application, forms should be unloaded after use with the
'unload_form' option. If a form is used repeatedly it is probably not
worth unloading it until the program is to terminate.


Services
--------

The following services should provide enough flexibility for you to define
and use some nice little menus, prompts, notices and forms in some of your
applications. If you get stuck and need an example, send some e-Mail to the
above address.

Menu Services : change_menu_attribs Changes colour attributes of menu
change_menu_escapes Change valid menu escape keys
clear_menu_in_pulldown Remove submenu of pulldown menu
define_menu Define a menu format
define_pulldown Define a pulldown menu
display_pulldown_header Display header line of pulldown
display_menu Display menu on screen
escape_fkey Find last used function key number
new_pulldown_cover Reload screen memory under pulldown
read_menu_selection Get user's menu choice
read_pulldown_selection Get choice from pulldown menus
remove_menu Remove menu from screen
remove_pulldown Remove pulldown menu & submenus
set_menu_help Define help function for pulldown
set_menu_option Enable or disable menu options
set_pulldown_help Define help function for pulldown

Prompt Services: clear_notice Clear a prepared notice
display_notice Display notice on screen
get_confirm Get user confirmation/rejection
notice_text Add line of text to prepared notice
prepare_notice Initialise notice creation
prompt_input Enter an input area in a notice

Form Services : display_form Display defined form on screen
edit_form Interactive form edit
get_field Obtain field value from form
get_field_choice_string Return the text of a Choice field
get_field_id Obtain numeric field ID from name
get_field_info Obtains field information block
get_form_info Obtains form infomation block
load_form Load form from .CFO form object
load_image_form Load form from linked-in module
put_field Put value into form field
remove_form Remove displayed form from screen
select_field Selects a field from a form
set_button_fn Defines a form button field handler
set_field_attrib Set colour attributes of field
set_field_mode Set field characteristics
set_field_verify Define field verification function
set_form_fnkey_fn Establish fn. key handler for form
set_form_help Define help function for form
set_form_mode Set form characteristics
unload_form Unload form from memory


Window Services: change_colour Change colours for subsequent I/O
clear_window Clear window and home cursor
close_window Remove window from screen
open_window Display window on screen
position_cursor Set cursor position in window
wprintf Formatted window output
wgets Editable window input

General : colour_attrib Get colour code for b/f colours
date_string Returns string form of a date type
date_value Returns date type of string form
set_mouse_mode Enables and disables mouse support


Mouse Support
-------------

The presence of a mouse driver is detected automatically by TCU and used by
default. The 'set_mouse_mode' service may be used to enable and disable the
mouse. The mouse may be used for menu option selection and form field
selection. The mouse mode may be interactively toggled on and off by using
the ALT-M key.

| Left Button Right Button
--------------------+----------------------------------------------------
Pulldown Menu Bar | Option Select No Action
Pop-Up menu | Option Select Menu Dismiss
Notices | Clears Notice Clears Notice
Form Edit | Move to selected field Move to first field
| If already on a button
| field, it is selected.
Field Select | Select Field Move to first field
Confirmation Box | Confirm Reject


change_colour
-------------

Function Changes the background and foreground colours for window I/O

Syntax #include "tcu.h"
int change_colour (WINDOW *window,
unsigned char attribute)

Remarks 'window' defines the window to be affected. 'attribute' is the
colour attribute and may be obtained with the 'colour_attrib'
service.

Return Value Returns TCU_OK on success, TCU_ERROR on error.


change_menu_attribs
-------------------

Function Changes a colour attribute of a menu. The menu must be defined
but need not be displayed.

Syntax #include "tcu.h"
int change_menu_attribs (MENU *menu,
int item,
unsigned char attribute)

Remarks 'item' identifies the attribute to change and must be one of
the following defined in 'menu.h':

MENU_TITLE Title of the menu
MENU_BOX Surrounding box of the menu
MENU_OPTION Option lines
MENU_SELECT Currently selected option line
MENU_UNAVAIL Unavailable option lines

'attribute' describes the new colour attribute to be used for
the selected item. It may be formed by using the 'menu_attrib'
function.

If the menu is currently displayed, the attribute will take
effect on the screen immediately.

Return Value Returns TCU_OK if the attribute change was successful and
TCU_ERROR if an error was encountered. An error is likely to
be due to a bad item specification or an undefined menu.


change_menu_escapes
-------------------

Function Changes the valid escape keys for a menu.

Syntax #include "tcu.h"
int change_menu_escapes (MENU *menu,
unsigned char escape_keys)

Remarks The escape keys define which keys are allowed to terminate the
interactive menu selection called with 'read_menu_selection'.
'escape_keys' is formed by logically ORing the following:

ESC_ESC ESC key
ESC_PGUP PgUp (Page Up) key
ESC_PGDN PgDn (Page Down) key
ESC_CLEFT Left arrow key
ESC_CRIGHT Right arrow key
ESC_FUNC Function key (F2 - F12)
ESC_CNTL_C CNTL/C key (ASCII 3)

The RETURN key is always a valid escape key, selecting the
currently selected menu option.

Note that F1 is reserved for help activation.

Return Value If the escape key change was successful, TCU_OK is returned,
otherwise TCU_ERROR is returned.


clear_menu_in_pulldown
----------------------

Function Removes a menu which is displayed under control of a pulldown
menu line.

Syntax #include "tcu.h"
int clear_menu_in_pulldown (PULLDOWN *pmenu);

Remarks This service should be used when a pop-up menu displayed under
control of a pulldown menu is to be removed from the screen.
Do not try to call 'remove_menu' directly as the pulldown menu
will become inconsistent with what is on the screen.

Return Value TCU_OK if the call was successful, otherwise TCU_ERROR.


clear_notice
------------

Function Removes a notice/prompt definition from memory.

Syntax #include "tcu.h"
int clear_notice (NOTICE *notice)

Remarks The definition of a notice or prompt is removed with the
call to 'clear notice'. An intervening 'prepare_notice'
call is required before using 'display_notice'.

Return Value Returns TCU_OK if the service was executed successfully,
otherwise TCU_ERROR is returned.


clear_window
------------

Function Clears the window and homes the cursor.

Syntax #include "tcu.h"
int clear_window (WINDOW *window)

Remarks The window is cleared with the currently active background
colour. The cursor is relocated to (1,1) relative to the
window.

Return Value Returns TCU_OK on success, TCU_ERROR on error.


close_window
------------

Function Close and remove a window from the screen.

Syntax #include "tcu.h"
int close_window (WINDOW *window)

Remarks The window is removed from the screen, the old screen contents
restored and the window memory is released to the system.

Return Value Returns TCU_OK on success, TCU_ERROR on error.


colour_attrib
-------------

Function Forms a colour attribute from the foreground and background
colour attributes.

Syntax #include "tcu.h"
unsigned char colour_attrib (int foreground,
int background)

Remarks 'colour_attrib' may be used to form the colour attribute
required by other menu and notice services. 'background' and
'foreground' represent the foreground colour and background
background colour respectively. Any colour defined in 'conio.h'
may be used if it is valid with the hardware being used.

Return Value Returns a compound attribute code.


date_string
-----------

Function Obtains the character string representation of a date value.

Syntax #include "tcu.h"
char *date_string (unsigned short date,
unsigned char presentation);

Remarks Returns a pointer to a static string buffer of 8 characters
which is overwritten with each call. 'date' specifies the
date value, i.e. val.v_date of FIELD_VALUE. 'presentation'
specifies either FLD_DAYFIRST or FLD_MONTHFIRST.

Return Value Returns a pointer to the static date string data.


date_value
----------

Function Returns a date type of a character date string.

Syntax #include "tcu.h"
unsigned short date_value (char *date,
unsigned char presentation);

Remarks Returns the date value of type val.v_date of FIELD_VALUE for
the specified string 'date'. 'presentation' specifies either
FLD_DAYFIRST or FLD_MONTHFIRST.

Return Value Returns the date type.


define_menu
-----------

Function Establish a definition for a menu, comprising characteristics
and content.

Syntax #include "tcu.h"
int define_menu (MENU *menu,
char *title,
unsigned char title_attrib,
unsigned char box_attrib,
unsigned char option_attrib,
unsigned char select_attrib,
unsigned char unavail_attrib,
unsigned char escape_keys,
unsigned char box_type,
char *options[],
unsigned char hot_key_attrib)

Remarks Uses the user declared element 'menu' to build a menu prototype
for subsequent menu functions. 'menu' is the address of a MENU
type. It is initialised with the call to define_menu and used
in subsequent menu functions. 'title' is an optional title for
the menu which, if present, will be displayed in the menu header
line. 'title_attrib' defines the colour attributes of the title
of the menu. 'box_attrib' defines the attributes of the menu
border. 'option_attrib' defines the attributes of the choices
of the menu. 'select_attrib' defines the attributes of the
currently selected menu option. 'unavail_attrib' defines the
attributes of menu options currently unavailable. 'escape_keys'
defines the set of keys permitted to exit from the menu select.
'box_type' defines the type of the surrounding menu box.

The attributes may be formed by using the function 'menu_attrib'
which builds the attribute byte. The two parameters are
foreground colour and background colour, and the return value
is of type attribute, i.e. unsigned char.

'escape_keys' is formed by logically ORing the following,
depending on which should be permitted to exit the menu choice.
The RETURN key is always valid for actively selecting the
current choice.

ESC_ESC ESCAPE key
ESC_PGUP Page Up key
ESC_PGDN Page Down key
ESC_CLEFT Left arrow key
ESC_CRIGHT Right arrow key
ESC_FUNC An unshifted function key F2 - F12
ESC_CNTL_C The CNTL/C key (ASCII 3)

Note that F1 is reserved for help activation.

'box_type' defines whether the box is singly or doubly lined
and is one of the following:

BOX_SINGLE Single line surround
BOX_DOUBLE Double line surround
BOX_BLANK Surrounded by blank spaces

'options' is a pointer to an array of the character strings
defining the menu choices. If 'hot_key_attrib' is non-zero
it should be a valid colour attribute used to display the
hot key character of a menu selection. When hot keys are
used, the FIRST character of each of the menu option strings
should be used to identify the character occurring in the rest
of the option string which is to be used as the hot key. E.g.,
the string "PDisPlay Customer" would use 'P' as the hot-key.
Note that only the first character matching the hot-key may
be used. If 'hot_key_attrib' is zero, no hot-keys will be
used at all.

Return Value define_menu returns TCU_OK if the call was successful or
TCU_ERROR if an error was detected in the processing.


define_pulldown
---------------

Function Defines a pulldown menu ready for display and activation.

Syntax #include "tcu.h"
int define_pulldown (PULLDOWN *pmenu,
unsigned char line_colour,
unsigned char option_colour,
unsigned char select_colour,
char *titles[],
unsigned char hot_key_attrib,
MENU *menus[]);

Remarks Defines a pulldown menu. 'pmenu' specifies the menu to be
defined, and should be declared by the caller. 'line_colour',
'option_colour' and 'select_colour' specify the colours of the
pulldown header line, the title texts and the currently selected
title respectively. The function 'colour_attrib' may be used
to obtain the compound colour codes for these colours.

'titles' is an array of strings which contain the titles used
in the header line. This list must be terminated with a NULL
pointer. If 'hot_key_attrib' is non-zero it should be a valid
colour attribute used to display the hot key character of a
pulldown menu selection. When hot keys are used, the FIRST
character of each of the title strings should be used to
identify the character occurring in the rest of the title
string which is to be used as the hot key. E.g., the string
"fConfiguration Menu" would use 'f' as the hot-key and will
highlight that character with the specified attributes in
the title when not selected. Note that only the first character
matching the hot-key may be used. If 'hot_key_attrib' is zero,
no hot-keys will be used at all.

'menus' is a pointer to an array of menus. These menus are
normal menus defined with 'define_menu', and may also be used
outside the control of the pulldown menu. Note that if a
pulldown menu title is to have no associated menu, the pointer
in that position should contain NULL.

Return Value Returns TCU_OK if the definition was successful, otherwise
returns TCU_ERROR.


display_form
------------

Function Displays a loaded form on the screen.

Syntax #include "tcu.h"
int display_form (FORM *form,
int x_pos,
int y_pos)

Remarks The form to be displayed must have been loaded with a call
to 'load_form'. 'form' specifies the address of a form
object. 'x_pos' and 'y_pos' specify the top-left corner of
the form. It is the callers responsibility to ensure that
the form to be displayed has room on the screen for the
specified position.

Return Value Returns TCU_OK is successful, otherwise TCU_ERROR.


display_menu
------------

Function Uses a predefined menu to display the menu on the screen
ready for interactive selection.

Syntax #include "tcu.h"
int display_menu (MENU *menu,
int x_pos,
int y_pos)

Remarks Displays a menu on the screen. No waiting for user input is
performed; the menu is displayed and control returns to the
caller.

'menu' is the address of a MENU type initialised with the
'define_menu' service. 'x_pos' and 'y_pos' define the screen
position of the top-left corner of the menu. Note that the
top-left corner of the screen is (1, 1).

Return Value The service returns TCU_OK if the menu was successfully
displayed and TCU_ERROR if an error condition was encountered.


display_notice
--------------

Function Displays a notice or prompt on the screen.

Syntax #include "tcu.h"
int display_notice (NOTICE *notice,
int x_pos,
int y_pos)

Remarks The notice/prompt is displayed with the top-left corner at
the position specified by 'x_pos' and 'y_pos'. If the notice
includes a prompt field, it may be interactively edited after
this call. The completion of a prompt input completes this
service and removes the prompt from the screen (though does
not remove its definition from memory until a call to the
'clear_notice' service. If the notice contains no prompt
input the user must press to RETURN key, the ESC key or a mouse
button to complete the call.

Note that with prompts, if the input field returns with a
length of -1, the user cancelled the input with the ESC key.
Since the length is a character type the caller must be sure
that the test against -1 is performed as a 'signed char' test,
either by using default signed characters, casting or testing
against the value 0xFF rather than -1.

Return Value TCU_OK if successful, else TCU_ERROR.


display_pulldown_header
-----------------------

Function Displays the header line of a pulldown menu without waiting for
a selection.

Syntax #include "tcu.h"
int display_pulldown_header (PULLDOWN *pulldown)

Remarks The header line for the pulldown menu 'pulldown' is displayed.
The pulldown menu must already have been defined. The function
is exactly as 'read_pulldown_selection' without the actual
selection of an item.

Return Value Returns TCU_OK if successful, else TCU_ERROR.


edit_form
---------

Function Interactively edit a loaded and displayed form.

Syntax #include "tcu.h"
int edit_form (FORM *form,
int start_field_id,
int *keypress)

Remarks The form may be interactively edited using the form and field
attributes and characteristics that exist at the time of the
call. 'form' specifies the address of a form object. The start
field-ID may be specified with 'start_field_id'. If set to 1,
the first valid field will be used. 'keypress' specifies the
address of an integer which will indicate the key used to escape
from the form input. 'keypress' will be one of the following
symbols:

FLD_ESCESC ESCAPE key used to quit
FLD_ESCCNTL CNTL/C key used to abort
FLD_ESCPGUP PgUp key
FLD_ESCPGDN PgDn key

The first two codes reflect that the form was exited abnormally
and the field values remain as they were before the edit. The
latter two are normal returns, and the form will have been
updated to reflect the edits made.

NOTE: Editing keys in a form are as follows:

-> : Move right one character
<- : Move left one character
Up Arrow : Move to previous field
Down Arrow : Move to next field
Home : Move to first character in field
End : Move to last character in field
CNTL PgUp : Move to first field in form
CNTL PgDn : Move to last field in form
F1 : Help
CNTL Home : Restore contents of field as when entered
CNTL End : Clear field
INSERT : Toggle insert mode
BACKSPACE : Delete character to the left of the cursor
Del : Delete character under the cursor
ESC : Escape (cancel) form edit
CNTL/C : Escape (abort) form edit
PgUp : Accept form edit
PgDn : Accept form edit

Return Value TCU_OK if the edit was successful, otherwise TCU_ERROR.


escape_fkey
-----------

Function Returns the last function key number used to escape a menu.

Syntax #include "tcu.h"
int escape_fkey (void)

Remarks If the function key escape mode is enabled, i.e., the option
MENU_FUNC is set in the escape keys of the menu, and the menu
was terminated with a function key ('read_menu_selection'
returned -ESC_FUNC), 'escape_fkey' will return the function
key used to leave the menu.

Return Value Returns 0 if no function key has been used, otherwise the
number of the function key, 1 = F2, 2 = F2, etc. 12 is the
last function key used. Keys F11 and F12 on may only be used
on machines with BIOS support for extended keyboards. Note that
the F1 key is reserved for activation of a user defined help
function.


get_confirm
-----------

Function Queries the user for confirmation or rejection

Syntax #include "tcu.h"
int get_confirm (int x,
int y,
unsigned char box_attrib,
unsigned char text_attrib,
char *text,
...)

Remarks Queries the user for confirmation of the 'text' which is
displayed in a box with colour attributes 'box_attrib' at
position (x,y). The text is displayed with attributes
'text_attrib'. The user may enter 'y', 'Y', 'n', 'N' or a
mouse button (left = confirm, right = reject) to confirm or
reject.

If the confirmation box would lie outside the screen area,
the confirmation text is changed automatically to the string
"Confirm (Y,N)?" and placed in the upper-left corner of the
screen.

Return Value Returns 0 for rejection or 1 for confirmation.


get_field
---------

Function Obtains a value for a form field.

Syntax #include "tcu.h"
int get_field (FORM *form,
int field,
FIELD_VALUE *val)

Remarks 'form' specifies the form object. 'field' is the field ID of
the field of which the value is to be obtained. 'val' is the
address of a FIELD_VALUE type object. The field value is a
structure which must be addressed according to the type of the
field (which should be known by the caller). The fields of the
structure are:

v_int : 32-bit signed integer for integers
v_float : 64-bit floating value for real types
v_string : Pointer to the string value
v_date : 16-bit integer coded date
v_logical : 8-bit data, 0 = FALSE, 1 = TRUE
v_choice.sel : 16-bit integer enumerated pointer

String values are copied into the user's calling address. This
means that 'v_string' should be set to point at the address
where the string is to be received. Failing to do this will
use a default pointer and will probably end in tears!

Date types represent the number of days since the start of the
19th century. This need not be known, though may be useful to
know that arithmetic operations on these types will represent
days.

Choice types are addressed using the sub-element 'v_choice.sel'
which is an index into the list of choices. I.e. 1 represents
the first selection, 2 the second, etc. 'v_choice.max' contains
the maximum valid index for the choice selection, though this
must not be modified by the application.

Return Value TCU_OK if the field was returned successfully, else TCU_ERROR.


get_field_choice_string
-----------------------

Function Obtains the text string associated with a field of 'Choice'
type.

Syntax #include "tcu.h"
int get_field_choice_string (FORM *form,
int field,
char *string);

Remarks 'form' specifies the form where field 'field' resides. The
field must be of type 'Choice' or the call will fail. The
string associated with the current selection will be placed

at the address specified as 'string'.

Return Value Returns FORM_Ok if the call was successful, else TCU_ERROR.


get_field_id
------------

Function Obtains the field ID for a named field.

Syntax #include "tcu.h"
int get_field_id (FORM *form,
char *field_name,
int *field_id)

Remarks Fields in forms may optionally be named. This allows the caller
to use meaningful names for fields rather than have to know
the logical field ID. 'form' identifies the form object,
'field_name' points to the name of the field for which the ID
is required. Case is NOT significant. 'field_id' points to the
integer into which the ID will be written. This may then be used
for subsequent field related operations. If 'field_id' is NULL,
it is not used.

Return Value Returns the ID of the field if present, else 0 if either an
error occurred or the field was not found.


get_field_info
--------------

Function Fills a struture with information about the specified field

Syntax #include "tcu.h"
int get_field_info (FORM *form,
int field_id,
FIELD_INFO *info);

Remarks The function fills the user-declared structure 'info' with
information about field 'field_id' in form 'form'. The structure
has the following fields:

struct FIELD_INFO {
char name[9]; /* Field name */
unsigned char type, /* FLD_INT, etc... */
size, /* Width of field in form */
decimal, /* Decimal places if appr. */
present, /* FLD_DAYFIRST, etc... */
xpos, /* Relative position in... */
ypos, /* ...the form */
verify_fn, /* 1 if verify fn. active */
help_fn, /* 1 if help fn. active */
usemin, /* 1 if has mimimum value */
usemax, /* 1 if has maximum value */
useval, /* 1 is has initial value */
usetmp; /* 1 if has string template */
union {
struct {
long min, /* Minimum value for FLD_INTs */
max; /* Maximum value for FLD_INTs*/
} i;
struct {
double min, /* Minimum value for FLD_FLOATs */
max; /* Maximum value for FLD_FLOATs */
} f;
struct {
unsigned short min, /* Minimum value for FLD_DATEs */
max; /* Maximum value for FLD_DATEs */
} d;
} range;
unsigned char colour; /* Colour attributes */
struct {
unsigned int ronly : 1, /* Read only flag */
noecho : 1, /* No-echo input flag */
fixtext : 1, /* Fixed text field flag */
param : 1, /* Non-editable field */
confirm : 1; /* ENTER confirmation flag */
} attr;
FIELD_VALUE val; /* Field value - see 'get_field' */
}

The fields in this structure represent the current state of the
form field. Use this service to obtain information about a field
rather than trying to access the field directly through the form
structure.

Return Value Returns TCU_OK if the field information was obtained without
error, else returns TCU_ERROR.


get_form_info
-------------

Function Fills a structure with information about the specified form

Syntax #include "tcu.h"
int get_form_info (FORM *form,
FORM_INFO *info);

Remarks The function fills the user-declared structure 'info' with
information about form 'form'. The structure has the following
fields:

struct FORM_INFO {
unsigned int num_fields; /* Number of fields */
char *title; /* Title of form */
unsigned char text_colour, /* Form colour */
field_colour, /* Default field colour */
title_colour, /* Title colour */
xpos, /* x-coordinate on screen */
ypos, /* y-coordinate on screen */
height, /* Height of form */
width, /* Width of form */
box_type, /* BOX_SINGLE, etc... */
mode; /* 1=Defined, 2=Displayed */
struct {
unsigned int ronly : 1; /* 1 if form read-only */
} attr;
} FORM_INFO;

The fields in this structure represent the current state of the
form. Use this service to obtain information about the form
rather than trying to access the information directly through
the form structure.

Return Value Returns TCU_OK if no error was encountered, else FORK_ERROR.


load_form
---------

Function Loads a form from the .CFO form object file into a form object.

Syntax #include "tcu.h"
int load_form (FORM *form,
char *filename)

Remarks This function operates on form object files which are produced
from the .CUF source files by the forms compiler. Form objects
normally have the type .CFO. 'form' identifies the form object
into which the form is to be loaded. 'filename' specifies the
name of the object file. See 'load_form_source' for further
details and a description of the source file format.

Return Value Returns TCU_OK if the form was loaded successfully, else
TCU_ERROR. TCU_ERROR will normally indicate an internal error
such as memory allocation problems, though it is possible that a
range error in date fields was invalidated. For example, if a
field was specified in the .CUF source file as:

FIELD = @10,10; Date (MonthFirst); Range (Today, 12/31/90)

then an error will occur trying to load this on or after the
date 12/31/90 as the range is invalidated.


load_image_form
---------------

Function Loads a form from a form image linked with the application.

Syntax #include "tcu.h"
extern char FORM_IMAGE;
int load_image_form (FORM *form,
char *FORM_IMAGE)

Remarks This function is directly equivalent to 'load_form', only it
loads forms internally from object modules linked in with the
application. This offers the advantage that an application may
be completely self-contained with no external form files to
supply. A disadvantage is that the application must be relinked
if the form definition changes. Use the /OBJECT or /LOADNAME
options of the forms compiler to generate linkable object
modules instead of the normal object files. 'FORM_IMAGE' is
the loadname of the object module which defaults to the file
name part of the original .CUF form definition file, but may be
specified using the /LOADNAME option of the forms compiler.

Return Value See 'load_form'


new_pulldown_cover
------------------

Function Reloads the saved screen cover under pulldown menus.

Syntax #include "tcu.h"
int new_pulldown_cover (PULLDOWN *pmenu);

Remarks This service should be used when the screen is changed outside
the control of a pulldown menu but while the menu is displayed.
This ensures that the further manipulation of the screen by the
pulldown menu services will result in a consistent display.
'pmenu' specifies the pulldown menu object.

Return Value TCU_OK is successful, else TCU_ERROR.


notice_text
-----------

Function Formats a string for inclusion in the body of a notice or
prompt.

Syntax #include "tcu.h"
int notice_text (NOTICE *notice,
char *fmt, ...)

Remarks The parameter list is identical to that of the 'printf'
function, and any valid 'printf' format control facilities may
be used with the exception of control codes such as '\n' and
'\b'. Blank lines are obtained by using an empty string, as in

status = notice_text (&my_notice, "");

Each call to 'notice_text' represents a line in the notice or
prompt. The size of the notice is automatically computed to
allow the longest line registered with 'notice_text'.

Return Value TCU_OK if the call was successful, else TCU_ERROR.


open_window
-----------

Function Opens a window and displays it on the screen.

Syntax #include "tcu.h"
int open_window (WINDOW *window,
int xpos, int ypos,
int xsize, int ysize,
char *title,
unsigned char box_attrib,
unsigned char window_attrib,
unsigned char title_attrib,
unsigned char box_type);

Remarks Opens a window of outside size 'xsize' x 'ysize' characters at
location (xpos,ypos). 'title' defines a textual title to appear
in the header line of the window, or may be omited by either
specifying NULL or a zero length string. 'box_attrib',
'window_attrib' and 'title_attrib' define the colour attributes
of the surrounding box, the window body and the title text
respectively. 'box_type' is one of:

BOX_SINGLE Single line surround
BOX_DOUBLE Double line surround
BOX_BLANK Surrounded by blank spaces

The user declared entity 'window' is filled with the initalised
window data and passed to subsequent windowing services.

Note that the window ALWAYS has a one character border, and the
size is including this border. A window of size 40 x 10 will
have a usable size 38 x 8, and this will be the maximum
cursor address. (1,1) always represents the top-left corner of
USABLE window space.

Return Value Returns TCU_OK on success, TCU_ERROR on error. An error will
normally be the result of specifying bad parameters or a memory
overflow. Bad parameters will often be caused by specifying
part of the window to be out of range of the screen.


position_cursor
---------------

Function Moves a window cursor to a specified point in the window.

Syntax #include "tcu.h"
int position_cursor (WINDOW *window,
int x, int y)

Remarks Moves the cursor to the specified location in the window.

Return Value Returns TCU_OK on success, TCU_ERROR on error. An error will
normally be attributable to an attempt to move the cursor
outside the window area.


prepare_notice
--------------

Function Initialises a notice/prompt.

Syntax #include "tcu.h"
int prepare_notice (NOTICE *notice,
char *title,
unsigned char title_colour,
unsigned char box_colour,
unsigned char notice_colour,
unsigned char box_type)

Remarks A notice or prompt is initialised with this service. The
parameters 'box_colour', 'notice_colour' and 'title_colour'
specify the colours of the surrounding box, the main notice
panel and the title string respectively. 'box_type' is one of
the following and defines the form of the perimeter box:

BOX_SINGLE : Single lined box
BOX_DOUBLE : Double lined box
BOX_BLANK : Surrounded by blank spaces

Text may be added to the notice with the 'notice_text' service
and the notice become complete at the call to 'display_notice'.
When the notice has been removed by the user, it remains
defined until a 'clear_notice' call is made. This allows a
notice to be used more than once without redefinition.

If no title is to be used, it should be specified as "", i.e.
an empty string. In this case the 'title_colour' parameter is
ignored.

Return Value Returns TCU_OK if successful, else TCU_ERROR.


prompt_input
------------

Function Adds an input field area to a notice.

Syntax #include "tcu.h"
int prompt_input (NOTICE *notice,
int xpos,
int ypos,
char *buffer,
unsigned char prompt_colour)

Remarks Only one input field may be present in a notice. If an input
field is specified, the notice becomes a 'prompt'. 'xpos' and
'ypos' specify the start position of the input area in the
notice panel. 'buffer' is a pointer to a user area where the
input is to be put. 'buffer' has the same form as the buffer
used in the library function 'cgets', i.e. buffer[0] must
specify the maximum length of the input field, and the actual
data is returned from buffer[2]. buffer[1] contains the number
of characters in the input field. This means 'buffer' must be
large enough to hold the maximum input string + 3 (to include
buffer[0], buffer[1] and the terminating '\0'. When the call
is made, the default string displayed will the contents of
the buffer at locations buffer[2] onwards. buffer[2] must be
set to '\0' if this feature is not required.

'prompt_colour' defined the colours to use for the prompt area.

When a notice has been converted to a prompt, the call to
'display_notice' will allow the user to enter the input string.
The notice disappears when the input is complete, whereas a
notice with no prompt area disappears when the user presses
the RETURN key.

Return Value TCU_OK if the call was successful, TCU_ERROR if an error
occurred.


put_field
---------

Function Loads a value into a field of a form.

Syntax #include "tcu.h"
int put_field (FORM *form,
int field,
FIELD_VALUE *val)

Remarks 'form' identifies the form into which the value is to be
loaded. 'field' is the field ID of the field, which may be
obtained by 'get_field_id' if the field is named in the CUF
file. 'val' is a pointer to a user declared FIELD_VALUE type
which contains the value to be loaded.

The value must comply with the type of the field and any
range declaration which has been made in the CUF file. String
lengths are checked, but compliance with string templates are
not.

See 'get_field' for details on how the field values in a form
are addressed.

If the form is currently displayed, the field is updated
immediately.

Return Value Returns TCU_OK if the call was successful, else TCU_ERROR.


read_menu_selection
-------------------

Function Returns the user selection from a defined and displayed menu.
If the user escapes from the menu with one of the permitted
escape keys, the key code is returned, otherwise the selected
menu option is returned.

Syntax #include "tcu.h"
int read_menu_selection (MENU *menu)

Remarks 'read_menu_selection' is an interactive function to obtain a
user selection from a displayed menu. Only valid escape keys
may be used to leave the interactive selection procedure.

Return Value If a valid menu option is selected, it is returned as a positive
integer; 1 represents the first choice, 2 the second, etc. If
an option is unavailable for selection, it will simply not be
returned under any circumstances. The numbering of the options
is sequential, including unavailable options; i.e. If the menu
has three possible options, the second of which is unavailable,
the third has the logical sequence number '3' even though it is
the second valid selection.

If the return is 0, an error was encountered. This will most
likely be due to either the menu not having been defined, or
not yet displayed.

If the return is negative, it represents the negative value of
the escape key used to leave the selection. E.g. to determine
if the ESC key was used to leave the menu, the following code
extract could be used:

selection = read_menu_selection (&mymenu);
if (!selection)
ERROR_CONDITION;
else
if (selection > 0)
NORMAL_SELECTION_MADE;
else
if (selection == -ESC_ESC)
ESCAPE_KEY_USED;
else
SOME_OTHER_ESCAPE_KEY_USED;


read_pulldown_selection
-----------------------

Function Returns a menu option selected under control of a pulldown menu.

Syntax #include "tcu.h"
int read_pulldown_selection (PULLDOWN *pmenu,
int *menu,
int *option);

Remarks 'pmenu' specifies the pulldown menu which is to be activated
and from which an option is to be read. The menu must have been
already defined with 'define_pulldown'. 'menu' returns the menu
from the pulldown header from which the selection was made (in
the range 1..No_of_menus) and 'option' returns the actual option
within the menu (in the range 1..No_of_options_in_menu).

If 'option' is zero and 'menu' is non-zero, the pulldown menu
option selected did not have an associated menu. If 'menu' is
zero the pulldown menu selection was aborted with the ESC key
and no selection was made.

Note that 'read_pulldown_selection' does not clear the menu(s)
from the screen on completion of the call (to allow a sequence
of user defined events to take place on selection of an option),
and may be called in sequence with intervening actions. Do NOT
attempt to perform operations using menus within the pulldown
system BETWEEN calls to 'read_pulldown_selection' other than the
provided 'clear_menu_in_pulldown' and 'new_pulldown_cover'
services. Use 'remove_pulldown' to clear the pulldown from the
screen.

Return Value Returns TCU_OK if the call was successful, else TCU_ERROR.


remove_form
-----------

Function Removes a form from the screen.

Syntax #include "tcu.h"
int remove_form (FORM *form)

Remarks 'form' specifies the form which is to be removed. The
definition is not removed; a 'display_form' is all that is
required to redisplay the form.

Return Value Returns TCU_OK if successful, TCU_ERROR if an error occurred.


remove_menu
-----------

Function Removes a displayed menu from the screen, restoring the original
screen contents.

Syntax #include "tcu.h"
int remove_menu (MENU *menu)

Remarks If the menu to be removed is overlaid with another menu, the
restoration of the screen will be incorrect. The user should
ensure that selections from overlaid menus are satisfied by
'read_menu_selection' and 'remove_menu' in the reverse order to
that in which they were displayed with 'display_menu'.

Return Value Returns TCU_OK if successful, or TCU_ERROR is unsuccessful.
If unsuccessful the menu is logically flagged as removed, thus
only leaving the screen incomplete.


remove_pulldown
---------------

Function Removes a pulldown menu from the screen, restoring the old
screen contents.

Syntax #include "tcu.h"
int remove_pulldown (PULLDOWN *pmenu);

Remarks 'pmenu' specifies the pulldown to be removed. Note that the
pulldown remains defined and may be activated again with the
'read_pulldown_selection' service.

Return Value TCU_OK if successful, or TCU_ERROR if an error occurred.


select_field
------------

Function Selects a single field from a form returning the field ID.

Syntax #include "tcu.h"
int select_field (FORM *form,
int start_field_id,
int *exitkey);

Remarks The service behaves exactly as 'edit_form', though disallowing
any editing of fields and terminating at the first field select
with the RETURN key. The form 'form' must be displayed. A start
field 'start_field_id' determines which field will be the first
one in which the cursor appears. If set to 1, the first valid
field will be used. 'exitkey' will return with the field-ID of
the field selected, or if negative will be one of the following
escape codes:

FLD_ESCESC ESCAPE key used to quit
FLD_ESCCNTL CNTL/C key used to abort
FLD_ESCPGUP PgUp key
FLD_ESCPGDN PgDn key

Return Value Returns with TCU_OK if no error, else TCU_ERROR.


set_button_fn
-------------

Function Establishes a button handler for a form.

Syntax #include "tcu.h"
int set_button_fn (FORM *form,
int far (*handler) (FORM *, int));

Remarks 'form' specifies the form for which the handler is to be
activated. 'handler' is the handler to which control is passed
when any button field on the form is selected. The two
parameters passed by the system to the handler specify the
form and the current button field ID.

The handler must return one of three possible values according
to the desired action:

0 = Continue as if no key had been pressed, i.e. no
actions subsequent to the handler will be made as a
result of the selection.

1 = Treat the keypress as a PgUp, i.e. save the results
of the form and exit. The exit code is FLD_BUTTONSAVE.

2 = Treat the keypress as an ESC, i.e. abort the form
entry and exit. The exit code is FLD_BUTTONESC.

To remove an existing handler, set the function to NULL.

Return Value Returns TCU_OK if the handler was successfully installed, or
TCU_ERROR if an error was encountered.


set_field_attrib
----------------

Function Sets the foreground and background colours of a field in a
form.

Syntax #include "tcu.h"
int set_field_attrib (FORM *form,
int field,
unsigned char new_colour)

Remarks 'form' identifies the form. 'field' is the field ID of the
field to be changed. This may be returned by 'get_field_id' if
the field is a named field. 'new_colour' specifies the new
colours of the field, which may be obtained with 'colour_attrib'

If the form is displayed, the colours are updated immediately.

Return Value Returns TCU_OK if successful, TCU_ERROR if an error occurred.


set_field_mode
--------------

Function Sets a field attribute for a field in a form.

Syntax #include "tcu.h"
int set_field_mode (FORM *form,
int field,
int mode)

Remarks 'form' specifies the form. 'field' is the field ID of the field.
'mode' is one of the following:

FORM_EDIT (default) : Allow the field to be changed
FORM_NOEDIT : Do not allow the field to be edited
FORM_ECHO (default) : Show field in form
FORM_NOECHO : Do not display contents of field
FORM_ENTER (default) : Cursor may enter field during edit
FORM_NOENTER : Cursor passes field by during edit
FORM_CONFIRM : Needs ENTER to confirm field entry
FORM_NOCONFIFM (dflt) : Prev. & next field confirm entry

If the field is set NOEDIT, attempting to change the value of
the field results in a tone.

Return Value Returns TCU_OK if the mode was successfully set, else returns
TCU_ERROR.


set_field_verify
----------------

Function Sets a verification function for a field.

Syntax #include "tcu.h"
int set_field_verify (FORM *form,
int far (*verify_fn)(FORM *, int,
FIELD_VALUE *))


Remarks 'form' specifies the form. 'verify_fn' is the address of an
integer function to perform the field verification. The function
is passed the form address, an integer value which is the field
ID and a pointer to the FIELD_VALUE structure of the field. The
value must not be changed in the handler routine, other that by
using 'put_field' with the passed 'form' parameter.

The function should return 0 if the field failed verification
and 1 if it verified successfully. If no field verification is
specified, the range constraints on the field (if any) are the
only checks made when the field is completed.

Field verification is checked when an attempt to change the
value of a field is made. This includes interactive form editing
and changes with 'put_field'.

Return Value Returns TCU_OK if verification was established successfully or
TCU_ERROR if an error occurred.


set_form_fnkey_fn
-----------------

Function Establishes a function key handler function for form entry.

Syntax #include "tcu.h"
int set_form_fnkey_fn (FORM *form,
int far (*handler) (FORM *, int, int));

Remarks 'form' specifies the form for which the handler is to be
activated. 'handler' is the handler to which control is
passed for all function keys. F1 is excluded as this is used
exclusively for help invokation. The parameters passed by the
system to the handler specify the form, the current field of the
form and the actual function key (2-12) in that order.

The handler must return one of three possible values according
to the desired action:

0 = Continue as if no key had been pressed, i.e. no
actions subsequent to the function key handler will
be made as a result of the keypress.

1 = Treat the keypress as a PgUp, i.e. save the results
of the form and exit. The exit code is FLD_FNKEYSAVE.

2 = Treat the keypress as an ESC, i.e. abort the form
entry and exit. The exit code is FLD_ENKEYESC.

To remove an existing handler, set the function to NULL.

Return Value Returns TCU_OK if the handler was successfully installed, or
TCU_ERROR if an error was encountered.


set_form_help
-------------

Function Associates a help function with a form.

Syntax #include "tcu.h"
int set_form_help (FORM *form,
void far (*help_fn)(int))

Remarks 'form' specifies the form, 'help_fn' is the address of a void
function which will be called when the F1 key is pressed when
the user is editing the form. The function is passed a single
integer value which is the field ID. This allows the function
to determine which field was selected when the help key was
pressed.

If no help function is defined for a field, the F1 key will
generate a warning beep.

Return Value Returns TCU_OK if the function was registered correctly, else
TCU_ERROR.


set_form_mode
-------------

Function Sets the form edit mode for a complete form.

Syntax #include "tcu.h"
int set_form_mode (FORM *form,
int mode)

Remarks 'form' specifies the form. 'mode' is one of the following:

FORM_EDIT (default) : Allow the form fields to be changed
FORM_NOEDIT : Do not allow the fields to be edited

If the form mode is set to EDIT, the field modes may still
prevent editing of individual fields.

Return Value Returns TCU_OK if the mode was successfully set, else returns
TCU_ERROR.


set_menu_help
-------------

Function Associates a help function with a menu.

Syntax #include "tcu.h"
int set_menu_help (MENU *menu,
void far (*handler)(int));

Remarks 'menu' specifies the menu to which the user defined help
function, 'handler', is to refer. Pressing the F1 function key
while in the specified menu will activate this function, passing
the currently selected menu option as a single integer parameter
to the help function to allow an option specific action to be
taken.

Use NULL as a 'handler' value to remove the help function. If
F1 is pressed when no help function is available, a single tone
will be sounded.

Return Value TCU_OK if the help function was successfully installed, else
TCU_ERROR.


set_menu_option
---------------

Function Enables or disables an option within a menu.

Syntax #include "tcu.h"
int set_menu_option (MENU *menu,
int choice,
int mode)

Remarks 'choice' identifies the menu choice to be changed. 'mode' is
0 to make a choice unavailable and 1 to enable a choice option.

Return Value Returns TCU_OK if the call was successful, TCU_ERROR if an
error was encountered.


set_mouse_mode
--------------

Function Enables or disables mouse support for menus and forms.

Syntax #include "tcu.h"
int set_mouse_mode (unsigned char mode)

Remarks The presence of a mouse is automatically detected and overrides
any selection made with this service. By default mouse support
if switched ON. If mode is 0, mouse support will be disabled.
If 1, it will be re-enabled. Note that the mouse mode may be
toggled interactively by using the ALT-M key.

Return Value TCU_OK if the service request was successful. TCU_ERROR means
that no mouse was detected, though does not constitute a real
error.


set_pulldown_help
-----------------

Function Associates a help function with a pulldown menu.

Syntax #include "tcu.h"
int set_pulldown_help (PULLDOWN *pmenu,
void far (*handler)(int));

Remarks 'menu' specifies the pulldown menu to which the user defined
help function, 'handler', is to refer. Pressing the F1 function
key while on any pulldown title will activate this function,
passing the currently selected menu option as a single integer
parameter to the help function to allow an option specific
action to be taken.

Use NULL as a 'handler' value to remove the help function. If
F1 is pressed when no help function is available, a single tone
will be sounded.

Return Value TCU_OK if the help function was successfully installed, else
TCU_ERROR.


wgets
-----

Function Receives user input from a window area.

Syntax #include "tcu.h"
int wgets (WINDOW *window,
int maxlength,
char *buffer,
int *actuallength)

Remarks Provides an editable input inside a window area. The input
field must be on one line and may not extend beyond the
window boundary. 'maxlength' specifies the maximum number of
characters to input. 'buffer' is the address of a buffer to
receive the input and should be at least maxlength+1 characters
in length to include the null terminator. 'actuallength' is
returned to indicate how many characters were present in the
input field.

The input buffer may be pre-loadad to give an inital input
string. If the field should be empty, 'buffer' should be a
zero length string.

If the length is returned as -1, the user cancelled the input
operation with ESC and the input string will be an empty
string.

Return Value TCU_OK on success, TCU_ERROR on error. Errors are likely to
be the result of specifying an input area outside the boundary
of the window.


wprintf
-------

Function Formatted output to a window.

Syntax #include "tcu.h"
int wprintf (WINDOW *window,
char *format,
arg1, arg2, arg3, ...)

Remarks As the C run-time library 'printf' function but to a window.
Long lines will wrap around.

Return Value TCU_OK on success, TCU_ERROR on error.


  3 Responses to “Category : C Source Code
Archive   : TCU_31.ZIP
Filename : TCU.DOC

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/