home *** CD-ROM | disk | FTP | other *** search
/ M.u.C.S. Disc 2000 / MUCS2000.iso / anwend / slectric / slctprog.txt < prev    next >
Text File  |  1996-11-28  |  10KB  |  220 lines
  1.                 Programmer's Guide to Selectric┐ V1.10
  2.                 --------------------------------------
  3.  
  4.                             November 1993
  5.  
  6.                   (c) 1992,93 by Stefan Radermacher
  7.  
  8.  
  9. Einleitung
  10. ----------
  11. Ja,  auch für Selectric┐ gibt's einen Programmer's Guide,  der  jedoch 
  12. zur  Zeit noch nicht so umfangreich ist.  Es ist mehr geplant als  bis 
  13. jetzt  verwirklicht wurde,  z.B.  wird man Selectric┐ irgendwann  auch 
  14. ein  sog.  virtuelles Verzeichnis übergeben können,  aus dem dann  Da-
  15. teien oder Objekte ausgewählen kann.  Ich will jetzt aber nicht zuviel 
  16. verraten.
  17.  
  18.  
  19. Die Möglichkeiten
  20. -----------------
  21. Ich  versuche  hier  mal  kurz die  Möglichkeiten  mit  Selectric┐  zu 
  22. umrei₧en, um so einen kleinen Überblick zu verschaffen:
  23. Selectric┐  installiert  einen  Cookie-Jar über  den  die  Applikation 
  24. Einstellungen  vornehmen  kann.  Das schlie₧t nicht nur  die  Optionen 
  25. oder  die  Sortierung  ein,  sondern auch die  Preset-Paths  und  -Ex-
  26. tensions.  Die  Struktur wurde in diesem Fall sehr flexibel  gestaltet 
  27. und sieht auf den ersten Blick etwas kompliziert aus.  Weiterhin  kann 
  28. man sich auch mehr als nur einen Dateinamen zurückgeben  lassen.  Auch 
  29. dies geschieht über den Cookie-Jar.
  30.  
  31. Der Cookie-Jar
  32. --------------
  33. Selectric┐ legt einen sog.  `FSEL'-Cookie an. Dieser zeigt an, da₧ man 
  34. in jedem Fall fsel_exinput() aufrufen kann,  auch wenn der neue  File-
  35. Selector  abgeschaltet  wurde.  Der Inhalt  `FSEL'-Cookies  ist  nicht 
  36. festgelegt, bei Selectric┐ zeigt er auf die folgende Struktur:
  37.  
  38. typedef struct
  39. {
  40.      unsigned long   id;           /* Selectric ID (`SLCT')      */
  41.      unsigned int    version;      /* Version (BCD-Format)       */
  42.      struct
  43.      {
  44.           unsigned           : 7;   /* reserviert                   */
  45.           unsigned todaytime : 1;   /* aktuelle Dateien mit Uhrzeit */
  46.           unsigned pthsav    : 1;   /* TOS-Pfade sichern            */
  47.           unsigned stdest    : 1;   /* Im Zielpfad bleiben          */
  48.           unsigned           : 1;   /* reserviert                   */
  49.           unsigned numsrt    : 1;   /* numerisches Sortieren        */
  50.           unsigned lower     : 1;   /* Kleinbuchstaben benutzen     */
  51.           unsigned dclick    : 1;   /* Ordner mit Doppelklick       */
  52.           unsigned hidden    : 1;   /* versteckte Dateien           */
  53.           unsigned onoff     : 1;   /* Selectric┐ AN/AUS            */
  54.      } config;
  55.      int       sort;               /* Sortiermodus (neg. = rev.)    */
  56.      int       num_ext;            /* Anzahl Extensions             */
  57.      char      *(*ext)[];          /* Standard-Extensions           */
  58.      int       num_paths;          /* Anzahl Pfade                  */
  59.      char      *(*paths)[];        /* Standard-Pfade                */
  60.      int       comm;               /* communication word         */
  61.      int       in_count;           /* input counter              */
  62.      void      *in_ptr;            /* input pointer              */
  63.      int       out_count;          /* output counter             */
  64.      void      *out_ptr;           /* output pointer             */
  65.      int       cdecl     (*get_first)(DTA *dta, int attrib);
  66.      int       cdecl     (*get_next)(DTA *dta);
  67.      int       cdecl     (*release_dir)(void);
  68. } SLCT_STR;
  69.  
  70.  
  71. Fangen wir mal an:
  72.  
  73. id             Das ist die ID von Selectric┐,  also `SLCT'.  Es reicht 
  74.                also  nicht nur den  `FSEL'-Cookie  abzfragen,  sondern 
  75.                mu₧ zusätzlich nich die ID checken.
  76.  
  77. version        Hier  steht  die  Versionsnummer  im  BCD-Format,  also 
  78.                0x0100 für 1.00.
  79.  
  80. config.
  81.        onoff        Über  dieses Bit wird Selectric┐ ein  (logisch  1) 
  82.                     bzw. ausgeschaltet.
  83.        hidden       Zeigt an,  ob versteckte Dateien angezeigt  werden 
  84.                     sollen.
  85.        dclick       Ordner erst auf Doppelklick öffnen.
  86.        lower        Pfadangaben    etc.    in   der   Hauptseite    in 
  87.                     Kleinbuchstaben anzeigen.
  88.        numsrt       Schaltet die numerische Sortierung ein.
  89.        stdest       Nach   Kopier/Verschiebe-Aktionen   im    Zielpfad 
  90.                     bleiben.
  91.        pthsav       Ist dieses Flag gesetzt,  so speichert  Selectric┐ 
  92.                     die   GEMDOS-Pfade   und  stellt  sie   kurz   vor 
  93.                     Verlassen wieder her.
  94.        todaytime    Bei   aktuellen  Objekten  Uhrzeit   statt   Datum 
  95.                     anzeigen.
  96.  
  97. sort           Konfiguriert  das Sortierkriterium,  dabei gelten  fol-
  98.                gende Werte:
  99.  
  100.                1    Sortiert nach dem Namen
  101.                2    nach Datum
  102.                3    nach Grö₧e
  103.                4    nach Typ bzw. Extension
  104.                5    unsortiert
  105.  
  106.                Ist der Wert negativ,  so wird rückwärts sortiert (z.B. 
  107.                -3 für `nach Grö₧e' und `rückwärts').
  108.  
  109. num_ext        Dieser  Wert  gibt  die Anzahl  der  möglichen  Preset-
  110.                Extensions  an.  Wird von der Applikation  eine  andere 
  111.                Anzahl  von Extensions übergeben,  so mu₧  dieser  Wert 
  112.                angepa₧t werden.  Selectric┐ V1.0 verarbeitet z.Zt. nur 
  113.                10 Extensions,  werden mehr übergeben, so wird der Wert 
  114.                von Selectric┐ aus auf 10 reduziert.
  115.  
  116. *(*ext)[]      Dieser  Zeiger  zeigt  auf ein Array  aus  Zeigern  auf 
  117.                Strings.   In   diesen  Strings  stehen   die   Preset-
  118.                Extensions.   Wird  der  Pointer  von  der  Applikation 
  119.                verändert,  so  mu₧ er auf eine  gleichartige  Struktur 
  120.                zeigen.  Der  Zeiger  (und auch die  Anzahl)  wird  von 
  121.                Selectric┐ aus wieder zurückgesetzt.
  122.  
  123. num_paths      Gibt  die Anzahl der Preset-Paths an  (ansonsten  siehe 
  124.                `num_ext').
  125.  
  126. *(*paths)[]    Das  ist für die Preset-Paths  da  (s.a.  `*(*ext)[]'). 
  127.                Bemerkung:  Das  übergeben von Pfaden  sollte  wirklich 
  128.                nur  dann angewendet werden,  wenn dies  auch  sinnvoll 
  129.                erscheint.  Weiterhin  sollte man diese Pfade  auch  in 
  130.                der  Applikation abspeichern können  (Selectric┐  spei-
  131.                chert  nur seine eigenen Extensions/Paths ab,  die  von 
  132.                der   Applikation  übergebenen  können  aber   trotzdem 
  133.                editiert werden!).
  134.  
  135. comm           Dieses Wort wird zur Kommunikation zwischen  Selectric┐ 
  136.                und der Applikation benutzt. Es wird nach Verlassen von 
  137.                Selectric┐ automatisch auf Null zurückgesetzt. Zur Zeit 
  138.                wird   nur  die  Richtung  Applikation  ->   Selectric┐ 
  139.                unterstützt.   Die   einzelnen  Bits   haben   folgende 
  140.                Bedeutung:
  141.  
  142.                Bit 0     Das   Programm   erwartet  mehr   als   einen 
  143.                          Dateinamen (s.a.  *out_ptr).  Dabei wird  die 
  144.                          gleiche  Struktur wie bei `paths'  und  `ext' 
  145.                          erwartet.  Ordner werden mit einem  Backslash 
  146.                          am Ende gekennzeichnet.
  147.                Bit 1     Dieses Bit gilt nur in Verbindung mit Bit  0. 
  148.                          Ist   das  Bit  gesetzt,   dann  werden   die 
  149.                          Dateinamen  durch  Leerzeichen  als  einziger 
  150.                          String  zurückgegeben,  fast so wie wenn  man 
  151.                          einem  Programm eine Kommandozeile  übergeben 
  152.                          würde.  Auch  hier sind die Ordner mit  einem 
  153.                          Backslash am Ende gekennzeichnet.
  154.  
  155.                Die  anderen Bits sind resrviert und  sollten  (besser: 
  156.                dürfen) nicht verändert bzw. benutzt werden.
  157.  
  158. in_count       z.Zt. unbenutzt
  159.  
  160. *in_ptr        z.Zt. unbenutzt
  161.  
  162. out_count      Die Applikation benutzt es, um anzugeben wieviele Items 
  163.                zurückgegeben werden sollen.  Selectric┐ schreibt  kurz 
  164.                vor dem Verlassen die tatsächliche Anzahl rein.
  165.  
  166. *out_ptr       Dieser   Pointer   mu₧   bei   Benutzung   auf    einen 
  167.                Speicherbereich  bzw.  Struktur,  welche innerhalb  der 
  168.                Applikation alloziert wurde, zeigen. Wichtig ist dabei, 
  169.                da₧ genügend Speicher alloziert wurde!
  170.  
  171.  
  172. Seit  Version 1.02 gibt es auch noch drei neue Funktionen,  mit  denen 
  173. man  noch  auf  eine  andere Art  und  Weise  mehrere  Dateinamen  zu-
  174. rückbekommen kann.  Sie arbeiten nach dem First/Next-Prinzip und haben 
  175. den  Vorteil,  da₧  die Hauptapplikation keinen Speicher für  die  Da-
  176. teiliste  zur Verfügung stellen mu₧.  Sie arbeiten äquivalent  zu  den 
  177. TOS-Routinen Fsfirst() und Fsnext(),  mit dem kleinen Unterschied, da₧ 
  178. man jeweils einen Zeiger auf eine DTA-Struktur übergeben  mu₧.  Ebenso 
  179. kann  man  bei  get_first() keine Dateimuster  übergeben,  da  das  ja 
  180. eigentlich  der User im Selector macht.  Weiterhin mu₧ nach dem  Holen 
  181. der  Dateinamen release_dir() aufgerufen werden,  damit Selectric  den 
  182. Speicher  wieder  freigibt.  Die ganze Aktion  mu₧  mit  wind_update() 
  183. eingeschachtelt werden, da es sonst zu Reentranzproblemen in Selectric 
  184. kommen kann.
  185.  
  186.  
  187. Bemerkung:     Die  Struktur ist in den Grundzügen kompatibel  zu  der 
  188.                aus FSELECT 1.2.x von Martin Patzel/Köhling,  d.h.  ID, 
  189.                Versionsnummer und das ON/OFF Bit sind an der  gleichen 
  190.                Stelle  zu  finden.  Der  Rest  ist  natürlich  nur  in 
  191.                Selectric┐ vorhanden.
  192.  
  193.  
  194. Nach dem Motto `ein Programm sagt mehr als tausend Worte' verweise ich 
  195. an dieser Stelle auf das Beispielprogramm und das Binding.
  196.  
  197.  
  198. Nachwort
  199. --------
  200. Bleibt  nur noch zu sagen,  da₧ noch einiges geplant ist,  welches  in 
  201. späteren  Versionen  auch verwirklicht wird,  jedoch  wollte  ich  das 
  202. nicht  `übers Knie brechen'.  Aber schon jetzt hat Selectric┐ die  um-
  203. fangreichste Programmierschnittstelle in der File-Selektor Welt.
  204. Ach ja,  das Binding und das Sample wurden nicht so intensiv getestet, 
  205. jedoch  sollten keine schwerwiegenden Fehler enhalten sein.  Für  Bug-
  206. Reports bin ich aber immer sehr dankbar.
  207.  
  208.  
  209. Meine Adresse ...
  210.  
  211. Stefan Radermacher
  212. Unter Krahnenbäumen 52-54
  213. 50668 Köln 
  214. Deutschland
  215. email: sr@k.maus.de
  216.  
  217.  
  218. It's not a trick, it's Selectric┐.
  219.  
  220.