FILEBOX -- File Selection


	1) Usage

	| OBJECT fbox[FILEBOX];

	A filebox instance has no state, but all information required
	for creating a file box is passed to it using arguments. There
	is only one single method called SELECT. When a select message
	is sent to a FILEBOX instance, the TTY of the sending program
	is put into raw mode and a file selection window is opened.
	When a file has been selected, the previous state of the TTY is
	restored. The window is not removed from the screen.

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


	2) Methods


	2.1 SELECT

	| FBOX.SELECT(x, y, sz, sy, cs, fs, title, path, sfx, buf)
	| ! Num,Num,Num,Num,Bvec,Bvec,Str,Str,Str|0,Str => name|0

	Sending the SELECT message to a FILEBOX instance opens a file
	selection window, lets the user select a file by navigating the
	a given directory structure, and returns either the name of the
	selected file or zero, if the operation has been cancelled by
	the user.

	Most of the arguments of SELECT control the location and style
	of the navigation window to be presented:

	X	the row of the upper left corner of the window
	.	(-1 = center)
	Y	the column of the upper left corner of the window
	.	(-1 = center)
	SX	the horizontal size (columns) of the window
	SY	the vertical size (rows) of the window.
	CS	the color set (see 'common data structures', 0=default)
	FS	the frame set (see 'common data structures', 0=default)
	TITLE	the title to be placed at the top of the window

	The window size will be rounded up, if it is not a multiple of
	2. If the given size is smaller than the minimum size of the
	window, then the minimum size will be used.

	Other parameters are used for transporting directory search
	information to the file box and back to the calling program:

	PATH	the directory to be presented upon startup
	SFX	the file suffix. Only files with the given suffix will
	.	be shown during navigation. (0 = list all files)
	BUF	a buffer of at least 256 characters which will be
	.	filled with the full path name of the selected file,
	.	if any.


	2.2 Navigation Keys and Window Layout

	A navigation window looks like this:

	| +-----------------Filebox Title------------------+
	| |                                                |
	| | ..__________________    Makefile_____________  |
	| | ____________________    Notes________________  |
	| | ____________________    config.cls___________  |
	| | ____________________    config.dir___________  |
	| | ____________________    config.ndx___________  |
	| | ____________________    config.t_____________  |
	| | /home/nmh/src/tools                            |
	| +------------------------------------------------+

	The characters used for drawing the frame around the box are
	taken from the FS argument. The lefthand side listing in the
	box lists directory names and the righthand side one lists file
	names.

	The TITLE is centered at the top of the box.

	The bottom line inside of the box displays the path name of the
	currently displayed directory.

	Long path names will be truncated on the left and prefixed with
	"...". Long files names will be truncated on the right and a
	highlighted "+" character will be appended.

	Color set usage is as follows:

	C_BACKGORUND	Box background
	C_FRAME		Box frame
	C_TEXT		Listing text
	C_SOTEXT	Highlighted text
	C_SELECT	Selection bar

	The following keys may be used to control file boxes (^X
	denotes [control]+[X], K_X denotes ttyctl.K_X):

	Key	Alt.	Description
	---	----	-----------
	K_DOWN	^N	move to next file
	K_UP	^P	move to previous file
	K_NEXT	^F	move to next page
	K_PREV	^B	move to previous page
	K_END	^E	move to last page
	K_HOME	^A	move to first page
	K_RIGHT	\r	directory list: change directory
	.	.	file list: select file and return
	K_LEFT	.	directory list: goto parent directory
	.	.	file list: go to directory list
	K_ESC	:	cancel selection and return
	TAB	.	move to other list


	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.