File Selector Box  (FSELECT.PRG)
by Martin Patzel, West Germany
translated into English by Andreas Ramos

All rights reserved      3/1989 by Martin Patzel    Version 3/89
-------------------------------------------------------------------------
What it is: FSELECT is an improved file selector window. It should be 
started from an AUTO folder. Whenever a file selector box is needed, 
FSELECT appears instead.
-------------------------------------------------------------------------
How to install FSELECT: (a very short manual) Place FSELECT.PRG in the 
AUTO folder on your start up disk. If you don't have a folder called AUTO, 
use the CREATE FOLDER option in your FILE menu from the desktop (and read 
your manual!)
-------------------------------------------------------------------------
Copyright message: This program and its files may be copied freely between 
all ST users according to the following conditions: FSELECT is copied with 
all files (FSELECT.PRG, FSELECT.INS, PATCH.PRG, BOXTEST.PRG, READ_ME.TXT).
No PD service may charge more than 3, 10DM, 40 DKr, or 4 US Dollars or 
the equivalent for this program. No portion of this program may be used 
for commerical purposes. The copyright of this program remains the 
property of Martin Patzel.
------------------------------------------------------------------------

FSELECT consists of:

FSELECT.PRG  The file selector.
FSELECT.ING  The keyboard definition.
PATCH.PRG    A program to add the changes to FSELECT.
BOXTEST.PRG  A small program to display the file selector.
FSELECT.TXT  Documentation for FSELECT.
------------------------------------------------------------------------

Contents:

  I. Changes since version 5/88
 II. Description of FSELECT.PRG
     1: The main window
     2: The options window
     3: Keyboard commands
III. Description of FSELECT.INS
 IV. Description of PATCH.PRG
  V. Appendix.

------------------------------------------------------------------------
I. Changes since version 5/88

Works with all TOS.
Keyboard commands.
Works with programs which were problems until now.
Accepts up to 16 drive buttons.
The directory can be displayed as "unsorted".
The path name can be saved in different ways.
Wordplus's FORMAT folder is correctly handled.
Path name correction was improved and expanded.
The box appears lower on the screen in order not to cover any possible 
information lines.
Several small errors were removed.
Uses the fsel_exinput() function from the new TOS 1.4. This function is 
part of TOS 1.4, but FSELECT has already incorporated it, and therefore 
every TOS can use it. See the PATCH.PRG.
The box is now in Vector 2 (GEM) and Vector 13 (BIOS). In both vectors, 
FSELECT remains within the XBRA protocolls.

------------------------------------------------------------------------
II. Description of FSELECT.PRG

Introduction:

FSELECT is a program for the AUTO folder on your boot disk (startup disk). 
Whenever your program needs a File selector box (opening a file, saving, 
etc.), the FSELECT will appear instead of the standard File Selector.

If you start FSELECT directly from the desktop, then please start a *.TOS 
or *.TTP program afterwards. This causes the FSELECT to become active. You 
can also just display a text file (double click on any text file ((*.DOC, 
*.DOK, *.TXT, etc)). Scroll through the first page by pressing the SPACE 
BAR, and then exit by pressing Q (QUIT). I regret that these extra steps 
are needed, but this has the advantage of allowing FSELECT to be used by 
any TOS version.

Normally, you should place FSELECT in your AUTO folder. This allows it to 
be automatically started.

FSELECT is designed to be comfortable in use. Wherever possible, a button 
is used so that you can just point and click. Buttons can be changed by 
you so that your favorite style can be used. Unnecessary drive buttons 
automatically disappear. The second window, which is rarely used, is kept 
out of sight. The most important / most used fields and buttons are 
grouped near the top right.

FSELECT is made up of two windows:
1: Main window.    Appears as a file selector.
2: Options window. Appears by clicking on the copyright bar.

------------------------------------------------------------------------
1: The Main Window

Copyright Bar: (first line)
Click here to go to the second window.
If your program uses a fsel_exinput(path,filename, button, message), then 
a message will appear here instead of the copyright message. This message 
can be up to 30 characters long.

Drive Buttons A, B, C, D... P:
Click on the drive button to go to that drive.
Only active drives are shown.
Up to 16 drives can be used.
Double-click on a button to see information about a disk.
If you change drives, FSELECT goes automatically to the path which you 
last used. FSELECT remembers where you were working on the disk. (Great!)

Path Name Bar: (second line)
This line shows the current path. This path can show up to 256 characters.
You can write in this path (edit the path). Afterwards, click in the Mover 
field (the gray bar over the file names). For example, you can write:

- "A". FSELECT automatically adds the ":*.*".
- Just a folder name. FSELECT enters the folder and shows the contents.
- Or any path name, such as "\FOLDER\DEF\*.C". Click on the Mover bar 
  afterwards.

File Name Bar: (third line, left side)
The name of the selected file appears here.
If you want to create or delete a folder, you must write its name here.

File Selector Window: (Eleven lines for files and folders)
This is made up of several elements:

Mover Bar:        The top grey bar.
Closer Button:    (Top left). Click on this to exit a folder.
Arrow Up/Down:    To scroll up or down. Auto-repeats.
Arrow left/right: Click here to show Name/Size/Date/Time.
Slider box:       (Right side) Point the mouse, press, and hold down the   
                  mouse ear to "grab" and move the slide bar.

The 11 file name lines:
These are the files/folders on your disk. To select one, click once and 
then click OK. Or, doubleclick on a name. This is the same as clicking OK. 
To "enter" a folder, click on it.

Extender buttons: (the twelve buttons to the right)
These let you select an extender. This "masks" the file names and lets you 
see only those files which you want. A file name is like a person's name: 
it has a first name and a family name. By using "*" for the first name and 
choosing ".DOC" for the last name (the extender), we can see all files 
that end with .DOC. If there are more than one character, you can use a 
question mark. (eg: you have files which end with both DOK and DOC. To see 
all of them, use an extender "*.DO?".) The double combination of "*.*" 
(pronouced "star point star") means anything first name and any extender 
name. This displays all files.

You can change (edit) the extenders. Doubleclick on them. When you finish, 
press RETURN or ENTER. To save these extenders, enter the second window 
and click "Save my Set-up."
Several suggested extenders:

*.*, *.DOC, *.DOK, *.DO?, *.SDO, *.LIB, *.BAK, *.TXT, *.PRG, *.RSC, *.IMG, 
*.PIC, *.PI?, *.CMP, *.INF, *.IN?, *.BAS, *.C, *.ASM, etc.

You should place your favorite/most common extenders on the left side, 
starting from the top. This makes it easier/quicker to reach them. The 
"everything.everything" mask (*.*) should always be at the top left.

FSELECT allows you to use "first" names as well. You can write "R*.*"; 
this shows all files that start with the character "R". This is useful for 
finding "READ_ME" files which can be "README, READ_ME, READ.ME, 
READ_ME.TXT, READ_MEE.DOC, etc). All of these variations will be shown.

Sorting: (Bottom right)
You can see files organized from top to bottom either by name 
(alphabetical order), extender (alphabetical order), size (smallest 
first), date/time (newest first), or unsorted.

Unsorted display lets you see the files as they really appear on the disk. 
This lets you see the order of files which are loaded in the AUTO folder 
or the accessories. Doubleclick on any sorting button to select 
"unsorted."

Note: In normal display, folders are always shown. But if you select 
unsorted display and use an extender mask (such as "*.DOC"), the folder 
will NOT be shown (unless it ends with .DOC). The folders remain invisible 
until you use a normal sorted display or use the *.* extender.

------------------------------------------------------------------------
2: The Options Window

Enter this window by clicking on the copyright bar.

This is made up of several parts.

1) Redraw:    (a) Fixed,  (b) Auto,   (c) Redraw.
2) Clamp:     (a) Path    (b) Extension
3) Path Sv    (a) Fsel    (b) TOS     (c) T->F
4) Delete Files/folder.
5) Create Folder.
6) Save Set up!

1) Redraw: When a file selector box is opened, the center of the screen is 
"erased" and the file selector box is "drawn" in that space. The ST has to 
know what that center was that it can be redrawn after the selector box 
goes away. Several programs have problems in redrawing the screen after a 
file selector box has been used. Other programs had parts of the message 
box missing. If your screen looks strange, then these options let you take 
care of this.

1c) Redraw mode: this lets the current program take care of redrawing the 
screen itself. FSELECT does not bother with making a buffer. If there are 
problems (grey bars refuse to disappear, etc), then select either AUTO or 
FIX.

1b) Auto mode: If Auto is selected, then FSELECT takes over the screen 
redrawing. The entire screen is moved into a 32KB buffer. When the 
selector box disappears, the entire screen is moved back from that buffer 
and the buffer is deleted. This is a extremely fast way to solve this 
problem.

Some programs (1ST Word, STAD, etc), however, grab the entire ST's memory, 
and don't leave 32KB left for the Auto redrawing. Therefore...

1a) Fix mode: The 32KB buffer is kept permanently: it is not deleted. Thus 
FSELECT, which is started first, grabs its 32KB buffer, and holds on to 
it.  (German: "fest" = firm, continuous, which I translated as "fixed"). 
If you find that you are running out of memory, select Redraw, save 
configuration, exit the file selector and all programs, and reboot.

So... normally, use AUTO mode. It is the fastest. If the FSELECT runs out 
of memory, then it automatically switches over into REDRAW mode. If that 
doesn't help, exit the program, switch to Fix mode, save configuration, 
and start up again. If you are using a large screen (19 inches or more), 
then the entire screen will take up too much memory. You should then use 
the REDRAW mode.

2) CLAMP: (Martin uses "Klemmen", which means "to clamp", or "fasten 
down". Not even Roget could suggest a better translation, so it remains 
"clamp.")

There are two ways of deciding which path/file/extender will appear. 
Either the box does it or the program does it. If the program decides, 
then it will always show a particular path/extender (eg. REDACTEUR always 
shows only \POLICES\*.LIB, which is rather annoying). This button lets you 
put a clamp on that stupid bug: you can choose to override the program. If 
you click on PATH or EXTENDER, then FSELECT will remember your selection 
and use that instead of the program's choice.

3) PATH-SV (Path Save)
There are minor bugs / poor design in TOS and several programs: the paths 
of disks arent remembered. There are several ways of dealing with this.

3a) FSEL(ect)

FSELECT takes over the entire work of keeping track of paths. 

3b) TOS
Previous versions of FSELECT used this method. The path is taken from 
GEMDOS. However, a small bug appeared with 1ST WORD: it couldn't find its 
FORMAT folder. Another bug: if you entered several folders 
(C:\Folder_A\Folder_B\Folder_C\*.*) and then switched disks, the file 
selector would look in Folder C. This is a common bug on the desktop: open 
a folder, change the disks, and press ESCAPE. TOS doesn't realize that the 
disk was changed, and shows the (empty) non-existent folder on the new 
disk.

3c) T(OS)->F(Select)
This mode is a compromise between the other two modes. Whenever a selector 
box is used, all of the active drives are checked and the current paths 
are read. This lets the box work in mode b: it opens in the path which was 
last used. You dont need to "enter" the folder again. Mode c then 
proceeds to work in mode a. This means that pathnames are not saved. 
Therefore, 1STWORDs FORMAT folder works with this mode. But there is a 
(very) small problem: the paths are not saved.
For harddisk users, there are several points. If you have only one drive 
and a harddisk and you have three windows open (A, B, and C), then you 
will get a message telling you to "Insert Disk B into Drive A". The 
solution for the file selector is to ignore A and B disk paths and to 
accept them only when you click on an A or B drive button.

Again, the best to use is mode a: FSEL.

4) Delete Files/Folder
This option deletes the file or folder which is in the selected line (Main 
window, line 3, NAME:_____).
To delete a file, click on it once (its name will appear in the file 
select line), click on the copyright message to go to the options window, 
and click on "Delete files/folder."
To delete a folder, write its name in the file select line, go to the 
options window, and click "Delete file/folder."
Using a keyboard command, you can press Control + Delete: whatever file is 
in the file select line in the main window will be deleted.
From the keyboard, you can delete files or folders by clicking on the 
files name so that it appears in the file select line or by writing the 
folders name in the file select line in the main window and then pressing 
Control + Delete.

5) Create Folder:
This option lets you create a folder. To create a folder, write its name 
in the file select line, click on the copyright box to go to the options 
window, and click "Create Folder."
From the keyboard, you can create folders by writing the new folder name 
in the file select line in the main window and then pressing Control + 
Insert.

6) Save my set-up!:
This lets you save your file selector settings. The sorting style, the 
default extenders, the Redraw-mode, the Clamping of paths or extenders, 
the option to save paths, and the file display in the file window (name, 
size, date/time). This option works only if FSELECT.PRG is in the AUTO 
folder in the boot drive and the program is not "write-protected" in any 
way. This option changes the program directly.

------------------------------------------------------------------------
3: Keyboard commands:

A major change in the new version of FSELECT are the keyboard commands. 
FSELECT can be used either by mouse or by keyboard. The entire options 
window can be used by keyboard commands; you do not need to go into the 
second window.

You can change the keyboard layout to suit yourself. This can be done by 
editing (changing) the file FSELECT.INS. Use any text editor or 1STWORD 
with WP MODE switched off. You must save in Non-WP mode (ASCII mode). Use 
PATCH.PRG to change the FSELECT to use the new layout.

All of the keycommands can be seen in FSELECT.INS. Here are the main ones:

Undo = Abort.
Help = Option Window.
Control + A, B, C, or up to P = Drive A, B, C, to P.
Control+Shift+ A, B, C, or up to P = Show disk info for disk A, B, C, etc.
Control + Insert = Create Folder.
Control + Delete = Delete file/folder.
Control + the numerical keypad = extender buttons.
Control + 1, 2, 3, etc above the QWERTY = select lines.
Control + Shift + 1, 2, 3, etc above QWERTY = Double click on line.
Control + w = Sort by name.
Control + x = Sort by extender.
Control + z = Sort by size.
Control + t = Sort by date.
Control + s = Save set up.

There are more for the Options box; if you want to use these, see 
FSELECT.INS.

(Translators comment: Many programs now use keyboard commands. FSELECT 
conflicts with the programs keyboard. You will need to edit and change 
the FSELECT keyboard layout. For example, REDACTEUR wordprocessor uses 
Control + A to abort a text. But FSELECT uses Control + A to access a 
drive. The result is that nothing happens. So, use a text editor (such as 
TEMPUS) to change FSELECT.INS. But... nearly every program with keyboard 
commands has a different layout; it is not easy to find unused keys or 
combinations. After working with FSELECT for several weeks now, I never 
use the keyboard commands (except for Create Folder/Delete file). It is 
much easier to use the mouse. It is impossible to remember the 50 or so 
commands for FSELECT. So... if you want to use it, its there. But if you 
dont, just ignore it.)

Other:
If you are having problems with booting, press ALTERNATE key during 
booting and FSELECT will not be used.

------------------------------------------------------------------------
III. Description of FSELECT.INS:

FSELECT.INS is a file which you can edit so that your own keyboard 
commands are used in FSELECT.PRG. Use any text editor or 1ST WORD (WP mode 
switched off) to change FSELECT.INS and save in ASCII mode. Use PATCH.PRG 
to patch the new changes into your FSELECT.PRG.

The order of lines is not important.
Any line which starts with a hash symbol is "commented out", or inactive.
You can also simply delete the line.
You can use either capital or small characters.
C = control, C+S = Control + Shift.
Each line begins with a keyword. It defines the object for the keycommand.
You can describe the key either as:

$4C = Hex format.
76  = Decimal format.
L   = ASCII format.

An example:

Drive0 = 5, shift, alt

This means that drive A can be used by pressing Shift plus 5. By pressing 
Alternate + 5, you can get information about the disk.

"ext0 = a, , shift"

By pressing only "a", you can select the first extender button. By 
pressing Shift + a, you can edit the extender button.

Only one object can be defined for one key. But you can use combinations 
of control, shift, and alternate with that key. Each object can have 
however multiple keys.

If you want to get rid of commands (control + delete is dangerous: it 
deletes whatever is in the selected line), simply delete the line and use 
PATCH.PRG to redefine your FSELECT.PRG.

Here is a syntax diagram in EBNF notation for all keywords (this is for 
programmers only).

     lines:    { line }
     line:     [ "fixdrives" :  ( OBJECT "=" KEY kshifts ) ] "\n"
     kshifts:  [ "," ( kshift [ "," kshift ] ) : ( "," kshift ) ]
     kshift:   SHIFT [ "+" SHIFT [ "+" SHIFT ] ]

                                     Shift key / key word.
SHIFT  : "shift"     : "s"           Left/Right shift key.
       : "alternate" : "alt"  : "a"  Alternate key.
       : "control"   : "ctrl" : "c"  Control key.


Key words for the main window.

KEY    : "DRIVE0"                    Drive 0 (normally A:)
       : "DRIVE1"                    Drive 1 (normally B:)
       : "DRIVE2"                    etc...
       : "DRIVE3"
       : "DRIVE4"
       : "DRIVE5"
       : "DRIVE6"
       : "DRIVE7"
       : "DRIVE8"
       : "DRIVE9"
       : "DRIVE10"
       : "DRIVE11"
       : "DRIVE12"
       : "DRIVE13"
       : "DRIVE14"
       : "DRIVE15"
       : "HEADER"                    Title bar.
       : "WICLOSE"                   Closer field.
       : "WIMOVE"                    Mover feild.
       : "WI0"                       1st file line in window.
       : "WI1"                       2nd file line in window.
       : "WI2"                       etc...
       : "WI3"
       : "WI4"
       : "WI5"
       : "WI6"
       : "WI7"
       : "WI8"
       : "WI9"
       : "WI10"
       : "WIUPARR"                   Window arrow up.
       : "WIDNARR"                     "      "   down
       : "WILTARR"                     "      "   left
       : "WIRTARR"                     "      "   right
       : "EXT0"                      Extender fields. "*.C"-"*.*"
       : "EXT1"
       : "EXT2"
       : "EXT3"
       : "EXT4"
       : "EXT5"
       : "EXT6"
       : "EXT7"
       : "EXT8"
       : "EXT9"
       : "EXT10"
       : "EXT11"
       : "SORTNAME"                  Sort by Name
       : "SORTEXT"                    "      Extension
       : "SORTDATE"                   "      Date
       : "SORTSIZE"                   "      Size
       : "EXIT"                      Abort the main box.


Key words for the Option window.

       : "OPFEST"                    Fixed mode.
       : "OPAUTO"                    Auto mode.
       : "OPREDRAW"                  Redraw mode.
       : "OPKLPF"                    Clamp the path.
       : "OPKLEX"                    Clamp the extender.
       : "OPSPFSEL"                  FSELECT remembers the path.
       : "OPSPTOS"                   TOS remembers the path.
       : "OPSPTOSFS"                 FSELECT takes path from select.
       : "OPREMOVE"                  Delete folder/file.
       : "OPMKDIR"                   Create folder.
       : "OPSAVE"                    Save set up.
       : "OPEXIT"                    Abort options box.
 OBJECT: ( "$" ( "0".."9" : "A".."F" ) { "0".."9" : "A".."F" } )
       : ( ( "0".."9" ) { "0".."9" } )
       : ( "'" " ".."~" "'" )
       : "Z("                        Keys from the numberic keypad.
       : "Z)"
       : "Z/"
       : "Z*"
       : "Z+"
       : "Z-"
       : "Z."
       : "Z0"
       : "Z1"
       : "Z2"
       : "Z3"
       : "Z4"
       : "Z5"
       : "Z6"
       : "Z7"
       : "Z8"
       : "Z9"
       : "ZCR"                       ENTER on the nummeric keypad.
       : "ENTER"                     ditto.
       : "HELP"                      Various special keys.
       : "UNDO"
       : "INSERT"
       : "HOME"
       : "CLR"
       : "CURUP"
       : "CURDOWN"
       : "CURLEFT"
       : "CURRIGHT"
       : "ESC"
       : "TAB"
       : "SPACE"
       : "BACKSPACE"
       : "RETURN"
       : "DELETE"
       : "F1"
       : "F2"
       : "F3"
       : "F4"
       : "F5"
       : "F6"
       : "F7"
       : "F8"
       : "F9"
       : "F10"

------------------------------------------------------------------------
IV. Description of PATCH.PRG:

This patches your new keyboard layout into the FSELECT program. Select the 
FSELECT.INS to be used; select the FSELECT to be changed, and press OKAY. 
If there are problems, youll get a message. Otherwise, press reset to 
load your new FSELECTor.

To use, doubleclick on PATCH.PRG. It first asks you for the .INS which you 
edited and then asks for the FSELECT.PRG which you want to change. Click 
OK. Thats it!

------------------------------------------------------------------------
V. Appendix:

BOXTEST.PRG is a little program so that you can see your file selector. 
You can change around with the FSELECT INF file, patch it into the FSELECT 
program, and then test it with BOXTEST and see how it came out.
To use, double click on BOXTEST. It asks for two lines: press any keys 
plus ENTER. Click on Exit to quit.

As always, do all tests and experiments on a separate disk. Make a backup 
first!

If you want the FSELECT source code, just send me 30 Deutsch Mark. Youll 
recieve 170 KB source code and 400 KB of files (all material in German).

Send a formatted, blank disk, a self-addressed envelope with postage (or 
international response coupons), and, of course, 30 DM or the equivalent 
in pounds, dollars, or gold.

Recommended compilers:
Mark Williams C, 3.0 or better. 2.1.7 is nearly okay.
For PATCH.PRG, lex and yacc are very useful (but not necessary).

Comments, criticism, and bug reports are always welcome!

My address:

Martin Patzel
Promenadeweg 15
7905 Dietenheim
West Germany

------------------------------------------------------------------------
History of FSELECT:

FSELECT was written by Martin Patzel, West Germany. It was written for the 
German and Spanish TOS. Heine Svendsen, of the 68000 UG in Denmark, asked 
him if it could be configured to the Danish TOS as well; Heine sent him 
the Danish TOS; Martin did even better and updated it to all TOS. He sent 
it to us; I translated it from German into English and sent copies to Paul 
Glover ST CLUB (England), Steve Delaney (Scotland) and Phil Reeves, 
Paragon Computers (Australia). We uploaded it onto BBS systems in England, 
Holland, Sweden, and other countries as well. Heine Svendsen translated it 
into Danish. All of these persons work together to distribute 
shareware/freeware/public domain to all ST users around the world.

FSELECT is a major improvement to the daily use of the ST. Programs do not 
fall out of the sky. Please support shareware and freeware authors. They 
are writing excellent programs for all users. If you use a shareware 
program, send the author the registration fee. If you use a freeware 
program, send the author money, several disks, or something. Only by 
cooperation and support between users and authors will we see more, better
programs. We recommend that you send 25 DM, 20 US$, 10 or 100 DKr. to:

Martin Patzel
Promenadeweg 15
7905 Dietenheim 1
West Germany.

-------------------------------------------------------------------------
For a complete copy of FSELECT (program, documentation, patch, INF file), 
find one of the PD services noted above in ST WORLD magazine or contact 
us.

For more information on Auto folders, file selectors, TOS, text editors, 
etc, see "YOUR SECOND MANUAL TO THE ATARI ST" by me. Available in English, 
German, Dutch, Swedish, and Danish. We can be contacted at:

Andreas Ramos
Jaegergaards Gade 142
DK-8000 Aarhus C,
Denmark, Scandinavia

Heine Busk Svendsen
Ingerslevs Boulevard 22.3
DK-8000 Aarhus C,
Denmark, Scandinavia

BBS: Denmark 86/202016
Tlf: Denmark 86/201117

-------------------------------------------------------------------------
