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

                             Januar 1992

                      (c) 1992 by Oliver Scheel

             ... this guide (however) goes Freaky Deaky!


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.
Der  ganze  Kram  mit der Programmierschnittstelle  ist  brigens  auf
meinem  Mist  gewachsen.  Anfragen  sind daher am besten  an  mich  zu
richten.


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        : 8;     /* reserved                   */
          unsigned pthsav : 1;     /* save and restore paths     */
          unsigned stdest : 1;     /* stay in destination path   */
          unsigned autloc : 1;     /* auto-locator               */
          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-mode (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             */
} 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  sol-
               len.
       dclick  Ordner erst auf Doppelklick ffnen.
       lower   Pfadangaben etc.  in der Hauptseite in  Kleinbuchstaben
               anzeigen.
       numsrt  Schaltet die numerische Sortierung ein.
       autloc  Aktiviert den Auto-Locator.
       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.

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!

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 wollten  wir  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 ...

Oliver Scheel
Rothehausstr. 28
W-5000 Kln 30 (Germany)

MausNet:  Oliver Scheel @ K
InterNet: Oliver_Scheel@k.maus.de


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


----
Rchzschreipfler (c) 1992 by Oliver Scheel
