                Programmer's Guide to Selectric V1.10
                --------------------------------------

                            November 1992

                  (c) 1992,93 by Stefan Radermacher


Introduction
---------------------------------------------------------------------------
Yes, with Selectric you even get a Programmer's Guide, however at the 
moment it's not so comprehensive as it could be. More will be added as new 
features are added to Selectric. For example so called 'virtual 
directories', from which folders or files can be selected, but i'd better 
not let too much out of the bag.

The possibilities
---------------------------------------------------------------------------
I will attempt to outline the overall possibilities of Selectric as 
briefly as possible:
Selectric installs a Cookie Jar from which the application parameters can 
be accessed. This provides not only the Options and the Sort mode but also 
the preset paths and extensions. The structure, although complicated at 
first glance, is very flexible. Furthermore more than one filename can be 
returned, which can be accessed via the Cookie Jar.

The Cookie Jar
---------------------------------------------------------------------------
Selectric sets up a Cookie named 'FSEL'. The Cookie is checked by calling 
the fsel_exinput() routine and also when the new File Selector is switched 
off. The contents of the 'FSEL' Cookie is not fixed, Selectric has the 
following structure:

typedef struct
{
     unsigned long   id;           /* Selectric ID (`SLCT')      */
     unsigned int    version;      /* version (BCD-Format)       */
     struct
     {
          unsigned           : 7;     /* reserved                   */
          unsigned todaytime : 1;     /* show time on current items */
          unsigned pthsav    : 1;     /* save and restore paths     */
          unsigned stdest    : 1;     /* stay in destination path   */
          unsigned           : 1;     /* reserved                   */
          unsigned numsrt    : 1;     /* numsort                    */
          unsigned lower     : 1;     /* use lowercase letters      */
          unsigned dclick    : 1;     /* open folder on dclick      */
          unsigned hidden    : 1;     /* show hidden files          */
          unsigned onoff     : 1;     /* Selectric ON/OFF          */
     } config;
     int       sort;               /* sort-fashion (neg. = rev.)    */
     int       num_ext;            /* number of extensions       */
     char      *(*ext)[];          /* preset extensions          */
     int       num_paths;          /* number of paths            */
     char      *(*paths)[];        /* preset paths               */
     int       comm;               /* communication word         */
     int       in_count;           /* input counter              */
     void      *in_ptr;            /* input pointer              */
     int       out_count;          /* output counter             */
     void      *out_ptr;           /* output pointer             */
     int       cdecl     (*get_first)(DTA *dta, int attrib);
     int       cdecl     (*get_next)(DTA *dta);
     int       cdecl     (*release_dir)(void);
} SLCT_STR;


We can hook into:

id             This is the ID for Selectric, also 'SLCT'. It's not enough 
	       to simply check the 'FSEL' Cookie, ID must also be checked.

version        The Version number in BCD-Format (eg 0x0100 is 1.00).

config.
       onoff      With this Bit set to one (logical 1) Selectric can be 
                  turned off.
       hidden     Controls whether hidden files will be displayed.
       dclick     Open folder with a double click.
       lower      Display pathnames, files, folders, etc in lower case.
       numsrt     Numerical sort switch.
       stdest     Remain in destination path after Move/Copy operations.
       pthsav     If this Flag is set Selectric stores the
                  GEMDOS path replaces it on exit.
       todaytime  Items which have today's datestamp are shown with
                  their timestamp instead

sort           Configures the sort criteria depending on the following 
	       values:
 
               1    Sort by Name
               2    by Date(s)
               3    by Size
               4    by Type (extension)
               5    No Sort

               If the value is negative, the display order is reversed, eg 
               -3 sorts by Size and in reverse.

num_ext        This value gives the number of existing preset extensions.
	       If an application passes over any other extension/s these 
	       must be taken note of.
               Selectric V1.0 can handle up to 10 Extensions, if more 
               extensions are passed then Selectric will reduce these to 
               10.

*(*ext)[]      This array index holds an index to all the strings. These 
	       strings contain the preset extensions. If the pointer from 
	       the application changes then the index (and number) must be 
	       reset from Selectric.

num_paths      Gives the number of preset paths (otherwise see 'num_ext').

*(*paths)[]    This is for the preset paths (see also '*(*ext)[]').
               Comment: bear in mind that path passing has not yet been 
               fully implemented yet. In the future Selectric will be able 
               to save these paths (at the current time Selectric only 
               saves its own paths/extensions). In spite of this, 
               extensions and paths passed to Selectric can be edited.

comm           This word is the communication between Selectric
               and the current application. On exit from Selectric this 
               word is automatically reset to zero. At this time only 
               the direction from the Application to Slectric is 
               supported. The individual bits have the following meaning:
               
               Bit 0     The program expects more than a single filename 
               		 (see also *out_ptr). Following the same structure 
               		 'paths' and 'ext' expects. Folders are denoted by 
               		 a trailing backslash.
               Bit 1     This bit is only used in conjunction with bit 0.
                         If bit 0 is set, then strings separated by space 
                         characters can be returned in a similar manner to 
                         using a Command Line. Here also folders can be 
                         denoted by a trailing backslash character.
                         
               The other bits are reserved and should not be changed by the 
               user.
               
in_count       Currently unassigned

*in_ptr        Currently unassigned

out_count      The application uses this to determine how many items have 
	       been returned. Selectric writes the appropriate number as 
	       it exits.

out_ptr        This must point to a contigous memory area within the 
	       application, which Selectric can use to write to. It is 
	       important that enough memory is allocated.

Version 1.02 introduced three new functions, which provide other ways of 
passing several filenames back to the application. Following the first/next 
principle offers the advantage that the main application doesn't need to 
reserve any memory for the filelist. These are equivalent to the TOS 
Fsfirst() and Fsnext() routines with the minor difference that the index 
must always be passed to the DTA Structure.

It is not possible to pass a file mask using get_first(), that the user has 
not actually selected (??Rubbish!??). After fetching the filenames the 
release_dir() call must be invoked so that Selectric can free the memory 
again. The entire action must take place with wind_update() turned on 
otherwise Selecreic could run into re-entrance problems.

Comment:       The structure is fundamentally compatible with FSELECT 1.2.x 
	       from Martin Patzel/Khling, therefore ID, Version number and 
	       the ON/OFF bit are the same. The rest is specific to 
	       Selectric.

With the quote 'one program says more than a thousand words' I will at 
this point refer you to the example program.

Finally
---------------------------------------------------------------------------
All that remains to say is that there are still things to do! Selectric 
already offers the most extensive range of commands in the File Selector 
world.
Oh yes, the example program hasn't been extensively tested however no 
major problems have been reported. I am always grateful to receive any bug 
reports.

Address:

Stefan Radermacher
Unter Krahnenbumen 52-54
50668 Kln
Germany 

Telephone: (from the UK) 010 49 221 122268

Email:  MausNet:  Stefan Radermacher @ K
	InterNet: sr@k.maus.de
	
It's not a trick, it's Selectric!
---------------------------------------------------------------------------
EOF

