FORM -- On-screen Forms


	1) Usage

	| OBJECT frm[FORM];

	A FORM instance has no state, but all information required for
	creating a custom form is passed to it using arguments. There
	is only one single method called COMPLETE. When a COMPLETE
	message is sent to an instance of FORM, the form described in
	the method arguments will be displayed on the screen. The
	terminal will be put into raw mode while the form is displayed,
	allowing the user to move the cursor around and change or edit
	the entries of the form. The form will not be removed from the
	screen when the user closes it.

	The FORM class uses color set and frame set structures
	described in the 'common data structures' section.


	2) Methods


	2.1 COMPLETE

	| FRM.COMPLETE(x, y, sx, sy, cs, es, fs, ks, items)
	| ! Num,Num,Num,Num,Bvec,Bvec,Bvec,Vec,Vec => 0|-1

	Sending the COMPLETE message to a FORM instance opens a custom
	form and lets the user complete it. It returns zero upon
	success and -1 in case of an error, usually an inconsistancy in
	the form description or other arguments. (Sorry for being so
	unclear at this point. Error handling is to be improved)

	Most of the arguments of COMPLETE control the location and
	style of the form to be presented:

	X	the column of the upper left corner of the form
	Y	the row of the upper left corner of the form
	SX	the horizontal size of the form
	SY	the vertical size of the form
	CS	the color set used in the form itself
	ES	the color set used to to display embedded edit and
	.	menu boxes when activated
	FS	the frame set used to display the form and embedded
	.	menues

	The last two arguments describe the form itself:

	KS	the key set used for navigation inside of the form
	ITEMS	the form description (see next section)

	The key set argument KS is a three-argument structure holding
	the keys required for moving the cursor to a specific field and
	closing the form. The FORM.KEYS structure is defined as
	follows:

	K_NEXT	move the cursor to the next field
	K_PREV	move the cursor to the previous field
	K_DONE	close the form

	Besides the specified keys, TAB can always be used to move to
	the next field and ttyctl.K_ESC (escape) can alwys be used to
	close the form.


	2.2 Form Descriptions

	Forms are described using a vector of FORM.ITEM structures.
	Each FORM.ITEM structure has the following members:

	I_TYPE	the type of the described item, see below
	I_X	the row of the upper left corner of the item
	.	relative to the upper left corner of the form
	I_Y	the column of the upper left corner of the item
	.	relative to the upper left corner of the form
	I_VALUE	the current value of the item
	I_DATA	additional data required by the item

	The type field may have one of the following values:

	T_TEXT	literal text to be printed on the form. The text
	.	it transported in the I_DATA field. I_VALUE is
	.	not used.
	T_INPUT	text input (prompt) field. I_VALUE holds the address
	.	of the string to be edited and I_DATA holds a two-
	.	element vector of the form [len,max], where LEN
	.	is the length of the field and MAX is the maximum
	.	number of characters to be entered.
	T_MENU	popup menu. When a T_MENU field is selected, a menu
	.	will pop up. I_VALUE holds the address of the current
	.	value. The current value will be pre-selected in the
	.	menu. When the user makes a selection, the variable
	.	pointed to by I_VALUE will be changed accordingly.
	.	I_DATA holds the menu description. See below.
	T_DONE	When such a field is selected, the form is closed.
	.	I_DATA holds the text to be displayed on this field.
	.	I_VALUE is not used.

	When defining a T_MENU item, the menu description should not be
	included in the table describing the form, because too deep
	nestings in table literals may break the T3X compiler (the
	specification allows three levels, but an embedded menu would
	create four). Instead, the menu description should be assigned
	to a variable and that variable should be included.

	Here is an example form description.

	| Menu := [
	|   [ 'T', "True"  ],      
	|   [ 'F', "False" ],      
	| 0 ];
	| ExampleForm := [
	|   [ form.T_INPUT,  7, 1, @Name,   [10,11]   ],
	|   [ form.T_TEXT,  18, 1, 0,       "="       ],
	|   [ form.T_MENU,  20, 1, @Choice, (Menu)    ],
	|   [ form.T_DONE,  14, 3, 0,       "[OK]"    ],
	| 0 ];

	When using the message

	| frm.complete(17, 5, 49, 10, 0, 0, "++++-|", 0, ExampleForm);

	to pass this description to an instance of FORM (frm), the
	following form would be displayed (assuming Choice=0 and
	Name="test"):

	| 	+------------------------------+
	| 	|      test_____  = True       |
	| 	|                              |
	| 	|             [OK]             |
	| 	+------------------------------+


	2.3 Colors and Keys

	Color usage in the FORM window itself (excluding embedded MENU
	and PROMPT objects) is as follows:

	C_BACKGROUND	Form background
	C_FRAME		Form frame
	C_TEXT		Literal (immutable) text
	C_SOTEXT	Embedded objects
	C_SELECT	Selection bar

	For the use of the embedded color set ES, see the section on
	the MENU and PROMPT classes.

	The keys used to manipulate embedded PROMPT and MENU objects
	are also described in the respective sections.


	3) Common Data Structures


	3.1 CSET -- Color Sets

	The color set structure CSET, which is implemented in the
	FILEBOX, FORM, MENU, and PROMPT classes, has the following
	members:

	Member		Used for...
	C_BACKGROUND	box backgrounds
	C_FRAME		drawing box frames
	C_TEXT		writing text
	C_SOTEXT	writing higlighted text
	C_SELECT	drawing the selection bar

	For the exact usage of this structure, see the description of
	the classes which use it. The CSET structure has the same
	layout in all classes. Therefore, one and the same color set
	may be used in file boxes, forms, menues, and prompt boxes.


	3.2 FSET -- Frame Character Sets

	The frame character set structure FSET, which is implemented in
	the FILEBOX, FORM, and MENU classes, has the following members:

	F_UL	upper left corner
	F_UR	upper right corner
	F_LL	lower left corner
	F_LR	lower right corner
	F_HL	horizontal lines
	F_VL	vertical lines

	NOTICE: FSET is a packed structure. To define one, use

	var fs::FSET;

	and to access its members, use fs::F_UL, fs::F_UR, etc.

	EXAMPLE: Using the FSET structure PACKED"1234-|" would result
	in a box of the form

	| 1----------2
	| |          |
	| |          |
	| 3----------4

	The FSET structure has the same layout in all classes.
	Therefore, one and the same frame character set may be used in
	file boxes, forms, and menues.