home *** CD-ROM | disk | FTP | other *** search
/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / zip / utility / slectric.lzh / DOKU / SLCTPROG.TXT < prev    next >
Text File  |  1986-02-06  |  9KB  |  208 lines
  1.                 Programmer's Guide to Selectric™ V1.0
  2.                 -------------------------------------
  3.  
  4.                              Januar 1992
  5.  
  6.                       (c) 1992 by Oliver Scheel
  7.  
  8.              ... this guide (however) goes Freaky Deaky!
  9.  
  10.  
  11. Einleitung
  12. ----------
  13. Ja,  auch für Selectric™ gibt's einen Programmer's Guide,  der  jedoch
  14. zur  Zeit noch nicht so umfangreich ist.  Es ist mehr geplant als  bis
  15. jetzt  verwirklicht wurde,  z.B.  wird man Selectric™ irgendwann  auch
  16. ein  sog.  virtuelles Verzeichnis übergeben können,  aus dem dann  Da-
  17. teien oder Objekte ausgewählen kann.  Ich will jetzt aber nicht zuviel
  18. verraten.
  19. Der  ganze  Kram  mit der Programmierschnittstelle  ist  übrigens  auf
  20. meinem  Mist  gewachsen.  Anfragen  sind daher am besten  an  mich  zu
  21. richten.
  22.  
  23.  
  24. Die Möglichkeiten
  25. -----------------
  26. Ich  versuche  hier  mal  kurz die  Möglichkeiten  mit  Selectric™  zu
  27. umreißen, um so einen kleinen Überblick zu verschaffen:
  28. Selectric™  installiert  einen  Cookie-Jar über  den  die  Applikation
  29. Einstellungen  vornehmen  kann.  Das schließt nicht nur  die  Optionen
  30. oder  die  Sortierung  ein,  sondern auch die  Preset-Paths  und  -Ex-
  31. tensions.  Die  Struktur wurde in diesem Fall sehr flexibel  gestaltet
  32. und sieht auf den ersten Blick etwas kompliziert aus.  Weiterhin  kann
  33. man sich auch mehr als nur einen Dateinamen zurückgeben  lassen.  Auch
  34. dies geschieht über den Cookie-Jar.
  35.  
  36. Der Cookie-Jar
  37. --------------
  38. Selectric™ legt einen sog.  `FSEL'-Cookie an. Dieser zeigt an, daß man
  39. in jedem Fall fsel_exinput() aufrufen kann,  auch wenn der neue  File-
  40. Selector  abgeschaltet  wurde.  Der Inhalt  `FSEL'-Cookies  ist  nicht
  41. festgelegt, bei Selectric™ zeigt er auf die folgende Struktur:
  42.  
  43. typedef struct
  44. {
  45.      unsigned long   id;           /* Selectric ID (`SLCT')      */
  46.      unsigned int    version;      /* version (BCD-Format)       */
  47.      struct
  48.      {
  49.           unsigned        : 8;     /* reserved                   */
  50.           unsigned pthsav : 1;     /* save and restore paths     */
  51.           unsigned stdest : 1;     /* stay in destination path   */
  52.           unsigned autloc : 1;     /* auto-locator               */
  53.           unsigned numsrt : 1;     /* numsort                    */
  54.           unsigned lower  : 1;     /* use lowercase letters      */
  55.           unsigned dclick : 1;     /* open folder on dclick      */
  56.           unsigned hidden : 1;     /* show hidden files          */
  57.           unsigned onoff  : 1;     /* Selectric™ ON/OFF          */
  58.      } config;
  59.      int       sort;               /* sort-mode (neg. = rev.)    */
  60.      int       num_ext;            /* number of extensions       */
  61.      char      *(*ext)[];          /* preset extensions          */
  62.      int       num_paths;          /* number of paths            */
  63.      char      *(*paths)[];        /* preset paths               */
  64.      int       comm;               /* communication word         */
  65.      int       in_count;           /* input counter              */
  66.      void      *in_ptr;            /* input pointer              */
  67.      int       out_count;          /* output counter             */
  68.      void      *out_ptr;           /* output pointer             */
  69. } SLCT_STR;
  70.  
  71.  
  72. Fangen wir mal an:
  73.  
  74. id             Das ist die ID von Selectric™,  also `SLCT'.  Es reicht
  75.                also  nicht nur den  `FSEL'-Cookie  abzfragen,  sondern
  76.                muß zusätzlich nich die ID checken.
  77.  
  78. version        Hier  steht  die  Versionsnummer  im  BCD-Format,  also
  79.                0x0100 für 1.00.
  80.  
  81. config.
  82.        onoff   Über  dieses Bit wird Selectric™ ein (logisch  1)  bzw.
  83.                ausgeschaltet.
  84.        hidden  Zeigt an,  ob versteckte Dateien angezeigt werden  sol-
  85.                len.
  86.        dclick  Ordner erst auf Doppelklick öffnen.
  87.        lower   Pfadangaben etc.  in der Hauptseite in  Kleinbuchstaben
  88.                anzeigen.
  89.        numsrt  Schaltet die numerische Sortierung ein.
  90.        autloc  Aktiviert den Auto-Locator.
  91.        stdest  Nach Kopier/Verschiebe-Aktionen im Zielpfad bleiben.
  92.        pthsav  Ist  dieses Flag gesetzt,  so speichert Selectric™  die
  93.                GEMDOS-Pfade  und stellt sie kurz vor Verlassen  wieder
  94.                her.
  95.  
  96. sort           Konfiguriert  das Sortierkriterium,  dabei gelten  fol-
  97.                gende Werte:
  98.  
  99.                1    Sortiert nach dem Namen
  100.                2    nach Datum
  101.                3    nach Größe
  102.                4    nach Typ bzw. Extension
  103.                5    unsortiert
  104.  
  105.                Ist der Wert negativ,  so wird rückwärts sortiert (z.B.
  106.                -3 für `nach Größe' und `rückwärts').
  107.  
  108. num_ext        Dieser  Wert  gibt  die Anzahl  der  möglichen  Preset-
  109.                Extensions  an.  Wird von der Applikation  eine  andere
  110.                Anzahl  von Extensions übergeben,  so muß  dieser  Wert
  111.                angepaßt werden.  Selectric™ V1.0 verarbeitet z.Zt. nur
  112.                10 Extensions,  werden mehr übergeben, so wird der Wert
  113.                von Selectric™ aus auf 10 reduziert.
  114.  
  115. *(*ext)[]      Dieser  Zeiger  zeigt  auf ein Array  aus  Zeigern  auf
  116.                Strings.   In   diesen  Strings  stehen   die   Preset-
  117.                Extensions.   Wird  der  Pointer  von  der  Applikation
  118.                verändert,  so  muß er auf eine  gleichartige  Struktur
  119.                zeigen.  Der  Zeiger  (und auch die  Anzahl)  wird  von
  120.                Selectric™ aus wieder zurückgesetzt.
  121.  
  122. num_paths      Gibt  die Anzahl der Preset-Paths an  (ansonsten  siehe
  123.                `num_ext').
  124.  
  125. *(*paths)[]    Das  ist für die Preset-Paths  da  (s.a.  `*(*ext)[]').
  126.                Bemerkung:  Das  übergeben von Pfaden  sollte  wirklich
  127.                nur  dann angewendet werden,  wenn dies  auch  sinnvoll
  128.                erscheint.  Weiterhin  sollte man diese Pfade  auch  in
  129.                der  Applikation abspeichern können  (Selectric™  spei-
  130.                chert  nur seine eigenen Extensions/Paths ab,  die  von
  131.                der   Applikation  übergebenen  können  aber   trotzdem
  132.                editiert werden!).
  133.  
  134. comm           Dieses Wort wird zur Kommunikation zwischen  Selectric™
  135.                und der Applikation benutzt. Es wird nach Verlassen von
  136.                Selectric™ automatisch auf Null zurückgesetzt. Zur Zeit
  137.                wird   nur  die  Richtung  Applikation  ->   Selectric™
  138.                unterstützt.   Die   einzelnen  Bits   haben   folgende
  139.                Bedeutung:
  140.  
  141.                Bit 0     Das   Programm   erwartet  mehr   als   einen
  142.                          Dateinamen (s.a.  *out_ptr).  Dabei wird  die
  143.                          gleiche  Struktur wie bei `paths'  und  `ext'
  144.                          erwartet.  Ordner werden mit einem  Backslash
  145.                          am Ende gekennzeichnet.
  146.                Bit 1     Dieses Bit gilt nur in Verbindung mit Bit  0.
  147.                          Ist   das  Bit  gesetzt,   dann  werden   die
  148.                          Dateinamen  durch  Leerzeichen  als  einziger
  149.                          String  zurückgegeben,  fast so wie wenn  man
  150.                          einem  Programm eine Kommandozeile  übergeben
  151.                          würde.  Auch  hier sind die Ordner mit  einem
  152.                          Backslash am Ende gekennzeichnet.
  153.  
  154.                Die  anderen Bits sind resrviert und  sollten  (besser:
  155.                dürfen) nicht verändert bzw. benutzt werden.
  156.  
  157. in_count       z.Zt. unbenutzt
  158.  
  159. *in_ptr        z.Zt. unbenutzt
  160.  
  161. out_count      Die Applikation benutzt es, um anzugeben wieviele Items
  162.                zurückgegeben werden sollen.  Selectric™ schreibt  kurz
  163.                vor dem Verlassen die tatsächliche Anzahl rein.
  164.  
  165. *out_ptr       Dieser   Pointer   muß   bei   Benutzung   auf    einen
  166.                Speicherbereich  bzw.  Struktur,  welche innerhalb  der
  167.                Applikation alloziert wurde, zeigen. Wichtig ist dabei,
  168.                daß genügend Speicher alloziert wurde!
  169.  
  170. Bemerkung:     Die  Struktur ist in den Grundzügen kompatibel  zu  der
  171.                aus FSELECT 1.2.x von Martin Patzel/Köhling,  d.h.  ID,
  172.                Versionsnummer und das ON/OFF Bit sind an der  gleichen
  173.                Stelle  zu  finden.  Der  Rest  ist  natürlich  nur  in
  174.                Selectric™ vorhanden.
  175.  
  176.  
  177. Nach dem Motto `ein Programm sagt mehr als tausend Worte' verweise ich
  178. an dieser Stelle auf das Beispielprogramm und das Binding.
  179.  
  180.  
  181. Nachwort
  182. --------
  183. Bleibt  nur noch zu sagen,  daß noch einiges geplant ist,  welches  in
  184. späteren  Versionen  auch verwirklicht wird,  jedoch wollten  wir  das
  185. nicht  `übers Knie brechen'.  Aber schon jetzt hat Selectric™ die  um-
  186. fangreichste Programmierschnittstelle in der File-Selektor Welt.
  187. Ach ja,  das Binding und das Sample wurden nicht so intensiv getestet,
  188. jedoch  sollten keine schwerwiegenden Fehler enhalten sein.  Für  Bug-
  189. Reports bin ich aber immer sehr dankbar.
  190.  
  191.  
  192. Meine Adresse ...
  193.  
  194. Oliver Scheel
  195. Rothehausstr. 28
  196. W-5000 Köln 30 (Germany)
  197.  
  198. MausNet:  Oliver Scheel @ K
  199. InterNet: Oliver_Scheel@k.maus.de
  200.  
  201.  
  202. It's not a trick, it's Selectric™.
  203.  
  204.  
  205. ----
  206. Rächzschreipfäler (c) 1992 by Oliver Scheel
  207.  
  208.