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

Formating:  Tabulator width 5

Andreas Kromke
20.11.95
Last changed
27.4.99

English translation: Peter West, July 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
								#define SORTDEFAULT -1

						 SORTBYNONE means the physical order on the 
						 disk.
						 SORTDEFAULT exists from Magic 6.10 onwards 
						 and means that the sort mode saved in the 
						 system will be used.
		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 '\'.
						 From MagiC 6.10 onwards the path may be 
						 initialised incompletely, as with fsel_xxx(), 
						 e.g. as an empty string. MagiC then 
						 completes the path in a sensible way.
		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.
						 From MagiC 6.10 onwards a null-pointer may 
						 be passed here, In which case MagiC then 
						 uses "*\0".
		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.
						 A null-pointer may be passed here.
		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.
