The extended file selector functions in the AES
===============================================

Formating:	Tabulator width 5

Andreas Kromke
20.11.95

English translation: Peter West, April 99


How do I recognise whether the functions are present?
=====================================================

Sub-function 7 of appl_getinfo() returns in bit 3 of 
ap_gout1 whether the fslx functions are present.
Declaration and call: See AES\WDIALOG.TXT

Bits in ap_gout1 in overview:
Bit 0:         wdlg_xx() functions are present (1)
Bit 1:         lbox_xx() functions are present (1)
Bit 2:         fnts_xx() functions are present (1)
Bit 3:		fslx_xx() functions are present (1)


Operation of the file selector
------------------------------

Key codes:

[Return]		No file selected:
				Returns the text in the editable field to the program.
			File selected:
				Returns the selected file.
			Folder selected:
				Opens the folder.
[Alt-A..Z]	Opens the respective drive in current directory
[Ctrl-Esc]	Rereads the directory
[Ctrl-H]
	or
[Ctrl-BS]		Goes back one directory level
[Ctrl-D]		Deselects all entries. With this one can force the return 
               of the input filename in place of the selected file.
[Cursor u/d]	Moves selection up/down
[Ctrl-Cursor]	Scrolls
[Sh-Cursor]	Moves selection by one page
[Sh-^-Cursor]	Scrolls page by page
[Home]		Selects topmost element
[Sh-Home]		Selects lowest element
				

Buttons:

A double-click on the "parent" field jumps back to the root directory.
A click on a line selects the object. In cases where several files are 
selectable (can be influenced through the system call), these can be 
selected with a Shift-click.
In each case one can deselect one file with Shift-click.


Open file selector window
-------------------------

Prototype:
		void * fslx_open(
			char *title,
			WORD x, WORD y,
			WORD	*whdl,
			char *path, WORD pathlen,
			char *fname, WORD fnamelen,
			char *patterns,
			WORD	cdecl (*filter)(char *path, char *name, XATTR *xa),
			char *paths,
			WORD sort_mode,
			WORD flags
			);

Call:
		contrl[0] = 190		Function number
		contrl[1] = 6			Entries in intin
		contrl[2] = 1			Entries in intout
		contrl[3] = 6			Entries in addrin
		contrl[4] = 1			Entries in addrout

		intin[0] = x
		intin[1] = y			Screen coordinates of the upper
							left corner of the window.
							For x=y=-1 the window will be centred.
		intin[2] = pathlen		Length of path buffer, i.e. maximum
							pathlength + 1 (for EOS)
		intin[3] = fnamelen		Length of filename buffer, i.e. maximum
							length of filename + 1 (for EOS)
		intin[4] = sort_mode	Sort mode for the display. The modes are:

								#define SORTBYNAME	0
								#define SORTBYDATE	1
								#define SORTBYSIZE	2
								#define SORTBYTYPE	3
								#define SORTBYNONE	4

							SORTBYNONE here means the physical order
							on the disk.
		intin[5] = flags		Various settings:

								#define DOSMODE	1
								#define NFOLLOWSLKS	2
								#define GETMULTI	8

							DOSMODE is the compatibility mode that
							is also used by fsel_(ex)input and 
							basically returns filenames in the
							8+3 format. For this all directories 
							are called with Dopendir(DOPEN_COMPAT).

							If NFOLLOWSLKS is set, then symbolic 
							links will not be followed, i.e. date 
							and time etc., as well as the XATTR-
							structure that is passed to <filter>,
							belong to the link itself.

							If GETMULTI is set, one can select and 
							pass several files at the same time.
							For this fslx_getnxtfile() is used 
							if fslx_evnt() or fslx_do() in the
							parameter <nfiles> signals that there 
							are still further files selected.

		addrin[0] = title		Window title of file selector, may be 
							NULL
		addrin[1] = path		Complete path, starts with drive and
							ends with '\'
		addrin[2] = fname		Buffer for the filename
		addrin[3] = patterns	Filemask, e.g. "*.TXT" or "*.PRG,*.APP". 
							The alternatively selectable masks are 
							separated by EOS and terminated by 
							EOS,EOS.
		addrin[4] = filter		May be NULL. The filter function is
							called before the mask comparison. If
							it returns 0 then the file is invalid,
							if 1 is returned then the filename will
							be displayed.
		addrin[5] = paths		Path "history" e.g. "C:\\BIN\\" etc.
							The alternatively selectable paths are 
							separated by EOS and terminated by 
							EOS,EOS.
		intout[0] = whdl		Window handle after successful opening
		addrout[0] = dialog		Returns a descriptor for further actions
							or NULL if an error has occurred (not 
							enough memory or no more window handles 
							free).

The corresponding descriptor will be created and the file selector window
opened.


Close file selector window or file selector dialog
--------------------------------------------------

Prototype:
		WORD fslx_close(
			void *fsd
			);

Call:
		contrl[0] = 191		Function number
		contrl[1] = 0			Entries in intin
		contrl[2] = 1			Entries in intout
		contrl[3] = 1			Entries in addrin
		contrl[4] = 0			Entries in addrout

		intout[0] = err		0 for error, else 1
		addrin[0] = fsd		Descriptor that was passed at the 
							successful opening of a file selector
							window.

The corresponding descriptor is cleared and the file selector window or 
dialog is closed.


Service file selector window
----------------------------

Prototype:
		WORD fslx_evnt(
			void *fsd,
			EVNT *events,
			char *path,
			char *fname,
			WORD *button,
			WORD *nfiles,
			WORD *sort_mode,
			char **pattern
			);

Call:
		contrl[0] = 193		Function number
		contrl[1] = 0			Entries in intin
		contrl[2] = 4			Entries in intout
		contrl[3] = 4			Entries in addrin
		contrl[4] = 1			Entries in addrout

		addrin[0] = fsd		Descriptor that was passed at a 
							successful opening of a file selector 
							window.
		addrin[1] = events		EVENT structure as for wdlg_evnt and
							fnts_evnt. The events are serviced by 
							the dialog if they are intended for the 
							associated window.
		addrin[2] = path		Pointer to the selected path if the 
							dialog was quit successfully, i.e. by a
							click on the OK button or by double-
							clicking on a file.
		addrin[3] = fname		Pointer to the selected filename if the 
							dialog was quit successfully, i.e. by a
							click on the OK button or by double-
							clicking on a file.
		intout[0]				Is 0 if the dialog is to be quit,
							else 1
		intout[1] = button
		intout[2] = nfiles
		intout[3] = sort_mode
		addrout[0] = pattern

Events, i.e. mouse clicks, messages and keypresses are passed on to the 
file selector window and serviced by it if appropriate. When an event 
has been serviced then the corresponding bit in the EVENT structure will 
be cleared.


File selector dialog
--------------------

Prototype:
	void * fslx_do(
			char *title,
			char *path, WORD pathlen,
			char *fname, WORD fnamelen,
			char *patterns,
			WORD	cdecl (*filter)(char *path, char *name, XATTR *xa),
			char *paths,
			WORD *sort_mode,
			WORD flags,
			WORD *button,
			WORD *nfiles,
			char **pattern );

Call:
		contrl[0] = 194		Function number
		contrl[1] = 4			Entries in intin
		contrl[2] = 4			Entries in intout
		contrl[3] = 6			Entries in addrin
		contrl[4] = 2			Entries in addrout

		addrin[0] = title
		addrin[1] = path
		addrin[2] = fname
		addrin[3] = patterns
		addrin[4] = filter
		addrin[5] = paths

		intin[0] = pathlen
		intin[1] = fnamelen
		intin[2] = sort_mode
		intin[3] = flags

		intout[0] = 1
		intout[1] = button
		intout[2] = nfiles
		intout[3] = sort_mode

		addrout[0] = fsd;
		addrout[1] = pattern

This function is a combination of fslx_open() and fslx_evnt(), but uses 
a dialog box without a window.


Examine further selected files
------------------------------

Prototype:
	WORD fslx_getnxtfile(
			void *fsd,
			char *fname
			);

Call:
		contrl[0] = 192		Function number
		contrl[1] = 0			Entries in intin
		contrl[2] = 1			Entries in intout
		contrl[3] = 2			Entries in addrin
		contrl[4] = 0			Entries in addrout

		addrin[0] = fsd		Descriptor that was passed at a 
							successful opening of a file selector 
							window.
		addrin[1] = fname
		intout[0] = result		0, when no further file is selected, 
							<fname> is unchanged.
							1, when a filename after <fname> was 
							copied.

If the flag GETMULTI was passed with fslx_do() or fslx_open(), then 
fslx_do() or fslx_evnt() will return in the parameter <nfiles> the 
number of files that are still selected in addition to the one in <fname>.
One can call these further files with fslx_getnxtfile(). Only after this 
may one call fslx_close().


Global system settings
----------------------

Prototype:
	WORD fslx_set_flags(
			WORD flags,
			WORD *oldval
			);

Call:
		contrl[0] = 195		Function number
		contrl[1] = 2			Entries in intin
		contrl[2] = 2			Entries in intout
		contrl[3] = 0			Entries in addrin
		contrl[4] = 0			Entries in addrout

		intin[0]	= 0
		intin[1]	= flags		Various flags, at present only:

								#define SHOW8P3	1

							SHOW8P3 is valid only for the display  
							of directories on DOS drives. It 
							corresponds to the switch "Show TOS 
							Files as '8+3'" in Magxdesk.

		intout[0] = result		0, if error
							1, if OK
		intout[1] = oldval		Previous value

This function is used (e.g. by MAGXDESK) in order to set the switch 
"Show TOS Files as '8+3'" for the file selector as well.
