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

                            November 1993

                  (c) 1992,93 by Stefan Radermacher


Einleitung
----------
Ja,  auch fr Selectric gibt's einen Programmer's Guide,  der  jedoch 
zur  Zeit noch nicht so umfangreich ist.  Es ist mehr geplant als  bis 
jetzt  verwirklicht wurde,  z.B.  wird man Selectric irgendwann  auch 
ein  sog.  virtuelles Verzeichnis bergeben knnen,  aus dem dann  Da-
teien oder Objekte ausgewhlen kann.  Ich will jetzt aber nicht zuviel 
verraten.


Die Mglichkeiten
-----------------
Ich  versuche  hier  mal  kurz die  Mglichkeiten  mit  Selectric  zu 
umreien, um so einen kleinen berblick zu verschaffen:
Selectric  installiert  einen  Cookie-Jar ber  den  die  Applikation 
Einstellungen  vornehmen  kann.  Das schliet nicht nur  die  Optionen 
oder  die  Sortierung  ein,  sondern auch die  Preset-Paths  und  -Ex-
tensions.  Die  Struktur wurde in diesem Fall sehr flexibel  gestaltet 
und sieht auf den ersten Blick etwas kompliziert aus.  Weiterhin  kann 
man sich auch mehr als nur einen Dateinamen zurckgeben  lassen.  Auch 
dies geschieht ber den Cookie-Jar.

Der Cookie-Jar
--------------
Selectric legt einen sog.  `FSEL'-Cookie an. Dieser zeigt an, da man 
in jedem Fall fsel_exinput() aufrufen kann,  auch wenn der neue  File-
Selector  abgeschaltet  wurde.  Der Inhalt  `FSEL'-Cookies  ist  nicht 
festgelegt, bei Selectric zeigt er auf die folgende Struktur:

typedef struct
{
     unsigned long   id;           /* Selectric ID (`SLCT')      */
     unsigned int    version;      /* Version (BCD-Format)       */
     struct
     {
          unsigned           : 7;   /* reserviert                   */
          unsigned todaytime : 1;   /* aktuelle Dateien mit Uhrzeit */
          unsigned pthsav    : 1;   /* TOS-Pfade sichern            */
          unsigned stdest    : 1;   /* Im Zielpfad bleiben          */
          unsigned           : 1;   /* reserviert                   */
          unsigned numsrt    : 1;   /* numerisches Sortieren        */
          unsigned lower     : 1;   /* Kleinbuchstaben benutzen     */
          unsigned dclick    : 1;   /* Ordner mit Doppelklick       */
          unsigned hidden    : 1;   /* versteckte Dateien           */
          unsigned onoff     : 1;   /* Selectric AN/AUS            */
     } config;
     int       sort;               /* Sortiermodus (neg. = rev.)    */
     int       num_ext;            /* Anzahl Extensions             */
     char      *(*ext)[];          /* Standard-Extensions           */
     int       num_paths;          /* Anzahl Pfade                  */
     char      *(*paths)[];        /* Standard-Pfade                */
     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;


Fangen wir mal an:

id             Das ist die ID von Selectric,  also `SLCT'.  Es reicht 
               also  nicht nur den  `FSEL'-Cookie  abzfragen,  sondern 
               mu zustzlich nich die ID checken.

version        Hier  steht  die  Versionsnummer  im  BCD-Format,  also 
               0x0100 fr 1.00.

config.
       onoff        ber  dieses Bit wird Selectric ein  (logisch  1) 
                    bzw. ausgeschaltet.
       hidden       Zeigt an,  ob versteckte Dateien angezeigt  werden 
                    sollen.
       dclick       Ordner erst auf Doppelklick ffnen.
       lower        Pfadangaben    etc.    in   der   Hauptseite    in 
                    Kleinbuchstaben anzeigen.
       numsrt       Schaltet die numerische Sortierung ein.
       stdest       Nach   Kopier/Verschiebe-Aktionen   im    Zielpfad 
                    bleiben.
       pthsav       Ist dieses Flag gesetzt,  so speichert  Selectric 
                    die   GEMDOS-Pfade   und  stellt  sie   kurz   vor 
                    Verlassen wieder her.
       todaytime    Bei   aktuellen  Objekten  Uhrzeit   statt   Datum 
                    anzeigen.

sort           Konfiguriert  das Sortierkriterium,  dabei gelten  fol-
               gende Werte:

               1    Sortiert nach dem Namen
               2    nach Datum
               3    nach Gre
               4    nach Typ bzw. Extension
               5    unsortiert

               Ist der Wert negativ,  so wird rckwrts sortiert (z.B. 
               -3 fr `nach Gre' und `rckwrts').

num_ext        Dieser  Wert  gibt  die Anzahl  der  mglichen  Preset-
               Extensions  an.  Wird von der Applikation  eine  andere 
               Anzahl  von Extensions bergeben,  so mu  dieser  Wert 
               angepat werden.  Selectric V1.0 verarbeitet z.Zt. nur 
               10 Extensions,  werden mehr bergeben, so wird der Wert 
               von Selectric aus auf 10 reduziert.

*(*ext)[]      Dieser  Zeiger  zeigt  auf ein Array  aus  Zeigern  auf 
               Strings.   In   diesen  Strings  stehen   die   Preset-
               Extensions.   Wird  der  Pointer  von  der  Applikation 
               verndert,  so  mu er auf eine  gleichartige  Struktur 
               zeigen.  Der  Zeiger  (und auch die  Anzahl)  wird  von 
               Selectric aus wieder zurckgesetzt.

num_paths      Gibt  die Anzahl der Preset-Paths an  (ansonsten  siehe 
               `num_ext').

*(*paths)[]    Das  ist fr die Preset-Paths  da  (s.a.  `*(*ext)[]'). 
               Bemerkung:  Das  bergeben von Pfaden  sollte  wirklich 
               nur  dann angewendet werden,  wenn dies  auch  sinnvoll 
               erscheint.  Weiterhin  sollte man diese Pfade  auch  in 
               der  Applikation abspeichern knnen  (Selectric  spei-
               chert  nur seine eigenen Extensions/Paths ab,  die  von 
               der   Applikation  bergebenen  knnen  aber   trotzdem 
               editiert werden!).

comm           Dieses Wort wird zur Kommunikation zwischen  Selectric 
               und der Applikation benutzt. Es wird nach Verlassen von 
               Selectric automatisch auf Null zurckgesetzt. Zur Zeit 
               wird   nur  die  Richtung  Applikation  ->   Selectric 
               untersttzt.   Die   einzelnen  Bits   haben   folgende 
               Bedeutung:

               Bit 0     Das   Programm   erwartet  mehr   als   einen 
                         Dateinamen (s.a.  *out_ptr).  Dabei wird  die 
                         gleiche  Struktur wie bei `paths'  und  `ext' 
                         erwartet.  Ordner werden mit einem  Backslash 
                         am Ende gekennzeichnet.
               Bit 1     Dieses Bit gilt nur in Verbindung mit Bit  0. 
                         Ist   das  Bit  gesetzt,   dann  werden   die 
                         Dateinamen  durch  Leerzeichen  als  einziger 
                         String  zurckgegeben,  fast so wie wenn  man 
                         einem  Programm eine Kommandozeile  bergeben 
                         wrde.  Auch  hier sind die Ordner mit  einem 
                         Backslash am Ende gekennzeichnet.

               Die  anderen Bits sind resrviert und  sollten  (besser: 
               drfen) nicht verndert bzw. benutzt werden.

in_count       z.Zt. unbenutzt

*in_ptr        z.Zt. unbenutzt

out_count      Die Applikation benutzt es, um anzugeben wieviele Items 
               zurckgegeben werden sollen.  Selectric schreibt  kurz 
               vor dem Verlassen die tatschliche Anzahl rein.

*out_ptr       Dieser   Pointer   mu   bei   Benutzung   auf    einen 
               Speicherbereich  bzw.  Struktur,  welche innerhalb  der 
               Applikation alloziert wurde, zeigen. Wichtig ist dabei, 
               da gengend Speicher alloziert wurde!


Seit  Version 1.02 gibt es auch noch drei neue Funktionen,  mit  denen 
man  noch  auf  eine  andere Art  und  Weise  mehrere  Dateinamen  zu-
rckbekommen kann.  Sie arbeiten nach dem First/Next-Prinzip und haben 
den  Vorteil,  da  die Hauptapplikation keinen Speicher fr  die  Da-
teiliste  zur Verfgung stellen mu.  Sie arbeiten quivalent  zu  den 
TOS-Routinen Fsfirst() und Fsnext(),  mit dem kleinen Unterschied, da 
man jeweils einen Zeiger auf eine DTA-Struktur bergeben  mu.  Ebenso 
kann  man  bei  get_first() keine Dateimuster  bergeben,  da  das  ja 
eigentlich  der User im Selector macht.  Weiterhin mu nach dem  Holen 
der  Dateinamen release_dir() aufgerufen werden,  damit Selectric  den 
Speicher  wieder  freigibt.  Die ganze Aktion  mu  mit  wind_update() 
eingeschachtelt werden, da es sonst zu Reentranzproblemen in Selectric 
kommen kann.


Bemerkung:     Die  Struktur ist in den Grundzgen kompatibel  zu  der 
               aus FSELECT 1.2.x von Martin Patzel/Khling,  d.h.  ID, 
               Versionsnummer und das ON/OFF Bit sind an der  gleichen 
               Stelle  zu  finden.  Der  Rest  ist  natrlich  nur  in 
               Selectric vorhanden.


Nach dem Motto `ein Programm sagt mehr als tausend Worte' verweise ich 
an dieser Stelle auf das Beispielprogramm und das Binding.


Nachwort
--------
Bleibt  nur noch zu sagen,  da noch einiges geplant ist,  welches  in 
spteren  Versionen  auch verwirklicht wird,  jedoch  wollte  ich  das 
nicht  `bers Knie brechen'.  Aber schon jetzt hat Selectric die  um-
fangreichste Programmierschnittstelle in der File-Selektor Welt.
Ach ja,  das Binding und das Sample wurden nicht so intensiv getestet, 
jedoch  sollten keine schwerwiegenden Fehler enhalten sein.  Fr  Bug-
Reports bin ich aber immer sehr dankbar.


Meine Adresse ...

Stefan Radermacher
Unter Krahnenbumen 52-54
50668 Kln 
Deutschland
email: sr@k.maus.de


It's not a trick, it's Selectric.

