home *** CD-ROM | disk | FTP | other *** search
/ M.u.C.S. Disc 2000 / MUCS2000.iso / anwend / bkite213 / develop_ / boxprog.doc next >
Text File  |  1999-02-15  |  33KB  |  835 lines
  1.  
  2.                           BoxKite V 2.13
  3.                           ==============
  4.  
  5.                 ---- Just another file selector ----
  6.  
  7.  
  8.  
  9.             Programmierdokumentation
  10.             ------------------------
  11.  
  12.  
  13.     Traps und Cookies
  14.     -----------------
  15.  
  16. BoxKite verbiegt die Vektoren für  Trap  #2 (GEM) und Trap #13 (BIOS).
  17. Die XBRA-Kennung ist 'HBFS'.
  18.  
  19. BoxKite legt die folgenden Cookies an:
  20.  
  21.     a) 'FSEL'
  22.  
  23. Über   den   'FSEL'-Cookie   wird   eine   Teilmenge   der  inzwischen
  24. wohlbekannten Selectric┐-Programmierschnittstelle realisiert.
  25.  
  26.     b) 'HBFS'
  27.  
  28. Der Wert des 'HBFS'-Cookies ist, wie schoon in früheren Versionen, die
  29. Einsprungadresse des  Trap-2-Handlers  von  BoxKite.  In  Version 2.00
  30. zeigt dieser Cookie auf die folgende Struktur (in C-Notation):
  31.  
  32. typedef struct
  33. {   unsigned int    branch;     /* Sprungbefehl um den struct herum */
  34.     unsigned long   magic;      /* Wert immer 'BxKt' */
  35.     unsigned int    version;    /* Versionsnummer: 0x200 für 2.00 */
  36.     long            resvd1;     /* reserviert */
  37.     long            resvd2;     /* reserviert */
  38.     long            resvd3;     /* reserviert */
  39.     long            resvd4;     /* reserviert */
  40. }
  41. BXKT_STR;
  42.  
  43. In zukünftigen Versionen wird diese Struktur möglicherweise erweitert;
  44. die  Versionsnummer  wird  das   Vorhandensein  solcher  Erweiterungen
  45. signalisieren.
  46.  
  47.     c) '_IDT'
  48.  
  49. Der   '_IDT'-Cookie   definiert    das    Format   der   Datums-   und
  50. Uhrzeitdarstellung übergreifend für  alle Anwendungsprogramme. BoxKite
  51. legt diesen Cookie, falls er  noch  nicht im System vorhanden ist, und
  52. initialisiert ihn  mit  den  für  Deutschland  üblichen Einstellungen.
  53. Wenn der Cookie bereits vorhanden ist, bleibt er unverändert.
  54.  
  55. Wenn beim Start  von  BoxKite  der  Cookie  'FSEL'  oder  'HBFS' schon
  56. existiert, wird  BoxKite  nicht  installiert,  da  in  diesem  Fall zu
  57. vermuten  ist,   da₧   schon   ein   anderer  residenter  Fileselector
  58. installiert ist (der Klügere gibt nach).
  59.  
  60. Der  Aufruf  von  BoxKite  über   'fsel_exinput()'  braucht  nicht  in
  61. 'wind_update()'-Aufrufe geklammert zu  werden.  Die nötigen Semaphoren
  62. werden      automatisch      gesetzt.      Die      Verwendung     von
  63. 'wind_update(BEG_UPDATE)' ist  aber  unschädlich,  da  BoxKite  diesen
  64. Semaphoren   im   Fensterbetrieb   selbsttätig   wieder   zurücksetzt.
  65. 'wind_update(BEG_MCTRL)' sollte dagegen  gemieden  werden,  da BoxKite
  66. ansonsten davon  ausgeht,  von  einem  modalen  Dialog  aus aufgerufen
  67. worden zu sein. Damit wird der Fensterbetrieb wirksam unterbunden.
  68.  
  69. Die folgenden Abschnitte  erläutern  zunächst  den  Aufruf von BoxKite
  70. über die Selectric-Schnittstelle und  anschlie₧en  den Aufruf über die
  71. FSLX-Schnittstelle. Die hier  in  Prosa beschriebenen Techniken werden
  72. in den Beispielprogrammen 'BSP_FSEL.C' bzw. BSP_FSLX.C' illustriert.
  73.  
  74.     Aufruf über das Selectric-Protokoll
  75.     -----------------------------------
  76.     
  77. Auch auf die Gefahr hin, bereits  Bekanntes zu wiederholen, möchte ich
  78. hier  die  Funktionsweise  der  Selectric┐-Schnittstelle  beschreiben,
  79. soweit sie auf BoxKite zutrifft.  Der  Wert des 'FSEL'-Cookies ist die
  80. Adresse einer Datenstruktur, über die  der Datenaustausch zwischen dem
  81. Anwendungsprogramm und dem Fileselector  erfolgt. Unter MiNT-Versionen
  82. mit Speicherschutz ist diese Datenstruktur für Anwendungsprogramme nur
  83. im  Supervisor-Mode   zugänglich.   Die   Datenstruktur   wird   in  C
  84. folgenderma₧en deklariert:
  85.  
  86. typedef struct
  87. {    unsigned long   id;           /* ID (`SLCT')                */
  88.      unsigned int    version;      /* Version (BCD-Format)       */
  89.      struct
  90.      {    unsigned           : 8;   /* reserviert                */
  91.           unsigned pthsav    : 1;
  92.           unsigned stdest    : 1;
  93.           unsigned           : 1;
  94.           unsigned numsrt    : 1;   /* numerisches Sortieren     */
  95.           unsigned lower     : 1;
  96.           unsigned dclick    : 1;   /* Ordner mit Doppelklick    */
  97.           unsigned hidden    : 1;   /* versteckte Dateien        */
  98.           unsigned onoff     : 1;   /* Fileselector AN/AUS       */
  99.      }         config;
  100.      int       sort;               /* Sortiermodus               */
  101.      int       num_ext;            /* Anzahl Extensions          */
  102.      char      *(*ext)[];          /* Standard-Extensions        */
  103.      int       num_paths;          /* Anzahl Pfade               */
  104.      char      *(*paths)[];        /* Standard-Pfade             */
  105.      int       comm;               /* communication word         */
  106.      int       in_count;           /* input counter              */
  107.      void      *in_ptr;            /* input pointer              */
  108.      int       out_count;          /* output counter             */
  109.      void      *out_ptr;           /* output pointer             */
  110.      int cdecl (*get_first)(XDTA *dta, int attrib);
  111.      int cdecl (*get_next)(XDTA *dta);
  112.      int cdecl (*release_dir)(void);
  113. }
  114. SLCT_STR;
  115.  
  116. Die Felder 'in_count' und  'in_ptr'  sind  weder  in Selectric noch in
  117. BoxKite benutzt. Die Felder  'pthsav',  'stdest' und 'lower' haben für
  118. Selectric eine  Bedeutung,  sind  aber  unter  BoxKite  als reserviert
  119. anzusehen. 
  120.  
  121. Alle Strings,  von  denen  in  diesem  Abschnitt  die  Rede  ist, sind
  122. selbstredend nullterminiert. Die Felder im Einzelnen:
  123.  
  124.     -  'id':  Dieses  Langwort  mu₧  den  Inhalt  'SLCT'  haben.
  125.     Andernfalls wurde der  'FSEL'-Cookie  von einem Fileselector
  126.     installiert,  der  das  Selectric-Protokoll  nicht versteht.
  127.     Bevor Sie das Selectric-Protokoll verwenden, müssen Sie also
  128.     dieses Feld testen.
  129.  
  130.     -   'version':   Hier    steht    die   Versionsnummer   des
  131.     Selectric-Protokolls im  BCD-Format,  also  0x100  für  1.0.
  132.     BoxKite trägt die Nummer  1.02  ein.
  133.  
  134.     - 'config': Die  einzelenen  Bits  in  diesem  Wort schalten
  135.     bestimme Features von BoxKite  bzw.  Selectric ein oder aus.
  136.     Die folgenden Bits sind für BoxKite relevant:
  137.  
  138.        onoff    steht dieses Bit auf 0, so wird die
  139.                 GEM-Dateiauswahl anstelle von Selectric bzw.
  140.                 BoxKite benutzt.
  141.        hidden   Gibt an, ob versteckte Dateien angezeigt  werden 
  142.                 sollen.
  143.        dclick   Ordner erst auf Doppelklick öffnen.
  144.        numsrt   Schaltet die numerische Sortierung ein.
  145.  
  146.     - 'sort': Konfiguriert  das  Sortierkriterium,  dabei gelten
  147.     folgende Werte:
  148.  
  149.                1    Sortiert nach dem Namen
  150.                2    nach Datum
  151.                3    nach Grö₧e
  152.                4    nach Typ bzw. Extension
  153.                5    unsortiert
  154.  
  155.     Negative Werte werden von BoxKite ignoriert.
  156.  
  157.     - 'num_ext',  'ext':  Über  diese  beiden  Felder  kann  die
  158.     Anwendung an BoxKite  eine  Liste  von Dateitypen übergeben.
  159.     Dazu  mu₧  sie  in  'num_ext'   die  Anzahl  der  Typstrings
  160.     eintragen, in 'ext'  die  Adresse  eines  Arrays von Zeigern
  161.     auf  die  fraglichen   Strings.   Wenn   BoxKite  die  Liste
  162.     übernommen hat,  wird  'ext'  wieder  auf die BoxKite-eigene
  163.     Liste zurückgebogen. Die  Applikation  mu₧ diese Felder also
  164.     vor jedem fsel_input() bzw. fsel_exinput() einstellen.
  165.  
  166.     -  'num_paths',  'paths':   Mit   diesen  Feldern  kann  die
  167.     Applikation BoxKite eine  neue  Liste  von Pfaden übergeben.
  168.     Das Verfahren  ist  dasselbe  wie  oben.  Auch  diese Felder
  169.     müssen vor jedem Aufruf eingestellt werden.
  170.  
  171.     Die  Pfade  und  Suchmasken,  die  über  diese Schnittstelle
  172.     übergeben  werden,  erscheinen  nicht  in  der  History  des
  173.     Pfadfeldes oder in den  Maskenknöpfen,  sondern immer nur im
  174.     Popup hinter der  übergebenen  Maske (oberster Maskenknopf).
  175.     Wenn der Anwender "Arbeit sichern"  betätigt, werden die von
  176.     BoxKite selbst  gespeicherten  Pfade  und  Typen  gesichert,
  177.     NICHT die von der Applikation festgelegten.
  178.  
  179.     - 'comm',  'out_count',  'out_ptr', 'get_first', 'get_next',
  180.     'release_dir':  Diese  Felder   werden   benötigt,   um  die
  181.     Rückgabe von mehreren  Dateinamen  an  die Hauptanwendung zu
  182.     realisieren. Näheres im folgenden Abschnitt.
  183.  
  184. Wie  geht  man  nun  vor,  um  eine  Mehrfachauswahl  von  Dateien  zu
  185. realisieren? Hier sieht  das  Selectric-Protokoll 3 Möglichkeiten vor.
  186. Allen ist gemeinsam, da₧ vor dem Aufruf  von BoxKite das Bit 0 im Wort
  187. 'comm' auf 1  gesetzt  werden  mu₧.  Die  Nutzung  der weiteren Felder
  188. hängt von der vorgesehenen Variante ab. Es sind dies die folgenden:
  189.  
  190.     a) Rückgabe über ein Zeigerarray
  191.  
  192. Um diese Rückgabemethode  anzufordern,  setzt  die  Anwendung das Feld
  193. 'comm' auf den Wert 1 (also Bit 0  auf 1 und alle anderen auf 0). Nach
  194. 'out_count' schreibt sie  die  Anzahl  der  Dateien, die sie höchstens
  195. erwartet. Nach 'out_ptr'  gehört  dann  die  Adresse  eines Arrays von
  196. Zeigern interpretiert, von  denen  jeder  auf  den  Speicher für einen
  197. Dateinamen verweist. Es  müssen  mindestens  so  viele  gültige Zeiger
  198. vorhanden sein,  wie  'out_count'  angibt,  und  jeder  Zeiger mu₧ auf
  199. einen hinreichend gro₧en  freien  Speicherblock verweisen. ACHTUNG: 13
  200. Bytes (incl. terminierender 0) sind NICHT  genug, 256 Bytes kommen der
  201. Sache schon näher.
  202.  
  203.     b) Rückgabe über eine Kommandozeile
  204.  
  205. Um diese Rückgabemethode  anzufordern,  setzt  die  Anwendung das Feld
  206. 'comm' auf den Wert 3 (also Bits  0  und  1 auf 1 und alle anderen auf
  207. 0). Nach 'out_count' schreibt sie  auch  hier  die Anzahl der Dateien,
  208. die sie  höchstens  erwartet.  'out_ptr'  wird  als  als Adresse eines
  209. Strings inetrpretiert, in  den  die  Namen  durch Leerzeichen getrennt
  210. geschreiben werden. Der String  mu₧  gro₧  genug für 'out_count' Namen
  211. incl. Leerzeichen sein. Beachten Sie  auch  hier,  da₧ ein Name bis zu
  212. 255 Zeichen umfassen kann.
  213.  
  214. Da diese Methode Leerzeichen  als  Trennzeichen  verwendet, kann es zu
  215. Problemen kommen, wenn  die  übergebenen  Dateinamen schon Leerzeichen
  216. enthalten. Um diesen Problemen  aus  dem  Wege  zu gehen, werden diese
  217. Namen in Hochkommata  eingefa₧t.  Eventuell  in  den  Namen enthaltene
  218. Hochkommata werden verdoppelt.
  219.  
  220.     c) Rückgabe über Abruffunktionen
  221.  
  222. Diese Technik ermöglicht  Ihnen,  eine  theoretisch unbegrenzte Anzahl
  223. von  Dateinamen  zurückzuerhalten.  Um  sie  anzufordern,  müssen  Sie
  224. zunächst 'comm' mit dem Wert 9 laden (also  Bit 0 und 3 auf 1 und alle
  225. anderen auf 0).  Wenn  'fsel_[ex]input()'  dann  signalisiert, da₧ der
  226. User 'Ok'  gewählt  hat,  rufen  Sie  zunächst  'get_first' auf. Diese
  227. Funktion erwartet als Parameter (und  zwar  in C-Manier auf dem Stack)
  228. einen  Zeiger  auf  eine  XDTA-Struktur  und  ein  Attributwort.  Eine
  229. XDTA-Struktur ist wie folgt zu deklarieren:
  230.  
  231. typedef struct
  232. {   char            d_reserved[21];
  233.     unsigned char   d_attrib;
  234.     unsigned int    d_time;
  235.     unsigned int    d_date;
  236.     unsigned long   d_length;
  237.     char            d_fname[256];
  238. } 
  239. XDTA;
  240.  
  241. Bis  auf  die  Länge  des  Namensfeldes  ist  sie  identisch  mit  der
  242. Standard-TOS-DTA. Das Namensfeld wurde  mit  Rücksicht  auf die langen
  243. Dateinamen erweitert.
  244.  
  245. 'get_first' funktioniert wie 'Fsfirst' und füllt die XDTA-Struktur mit
  246. Informationen über die erste  selektierte  Datei. Es werden nur solche
  247. Dateien  zurückgegeben,  die  die   Attribute   haben,   die  mit  dem
  248. übergebenen Attributwort  korrespondieren  (die  Werte  werden genauso
  249. behandelt wie  von  GEMDOS  bei  Fsfirst(),  d.  h.  Dateien  mit  den
  250. Attributen 0,  "Archiv"  oder  "schreibgeschützt"  erscheinen  immer).
  251. Wenn eine Datei  gefunden  wurde,  gibt  'get_first()'  eine 0 zurück.
  252. Dann können Sie mit  'get_next()'  nacheinander  alle weiteren Dateien
  253. anfordern, bis ein Returncode  ungleich  0 auftritt. Danach müssen Sie
  254. 'release_dir()' aufrufen,  woraufhin  BoxKite  den  von der Dateiliste
  255. belegten Speicher  freigibt.  Diesen  ganzen  Ablauf  sollten  Sie  in
  256. 'wind_update' einschachteln, damit kein  anderer  Proze₧  auf die Idee
  257. kommt, zwischenzeitlich eine  Dateiauswahlbox  aufzurufen. Falls diese
  258. Beschreibung etwas zu abstrakt geraten ist,  werfen Sie einen Blick in
  259. BEISPIEL.C.
  260.  
  261. Seit Version 1.71  enthält  BoxKite  eine  Schnittstelle, über die die
  262. Hauptapplikation GEM-Messages,  die  sich  auf  hintenliegende Fenster
  263. beziehen, erhalten kann. Damit entfällt  der Redraw mit kleinen bunten
  264. Doppeldeckern.
  265.  
  266. Das  Grundprinzip  ist  ganz  einfach.  Sie  übergeben  an  BoxKite im
  267. 'fsel_exinput()'  als  zusätzlichen   Parameter  die  Einsprungadresse
  268. einer Routine, die  die  Behandlung  dieser  Messages übernimmt. Diese
  269. Routine mu₧ in C folgenderma₧en deklariert werden:
  270.  
  271.     void cdecl message_handler(int *message)
  272.  
  273. Sie sollte also auf  dem  Stack  (in  C-Manier) als einzigen Parameter
  274. einen Zeiger auf den  Message-Puffer  erwarten, der von 'evnt_multi()'
  275. gefüllt wird. Einen Rückgabewert  braucht  sie  nicht zu erzeugen. Vor
  276. dem Aufruf dieser Routine schaltet  BoxKite  wieder  auf den Stack der
  277. Hauptapplikation um.
  278.  
  279. Der Zeiger auf diese  Routine  wird  im  GEM-Feld 'addrin' als vierter
  280. Parameter an 'fsel_exinput()' übergeben.  Um  deutlich  zu machen, da₧
  281. hier ein gültiger Zeiger steht, mu₧  'contrl[3]' auf 4 gesetzt werden.
  282. Andere Fileselectoren sollten sich nicht an dieser Änderung stören.
  283.  
  284. In BEISPIEL.C finden Sie auch für dieses Feature ein Anwedungsbeispiel
  285. sowie ein in diesem  Sinne  erweitertes  Binding für 'fsel_exinput()'.
  286. Dieses Binding läuft mit Pure  C 1.1. Eine Assembler-Version desselben
  287. Bindings liegt als Quelltext und als Objekt-Datei im DR-Format bei.
  288.  
  289.     Aufruf über die FSLX-Schnittstelle
  290.     ----------------------------------
  291.  
  292. Mit MagiC Version 4.x wurden zusätzliche Systemaufrufe eingeführt, die
  293. die Dateiauswahl im Fenster explizit  unterstützen und daher keine der
  294. Schwächen haben, mit denen  sich  BoxKite  bisher herumschlagen mu₧te.
  295. Daher unterstützt BoxKite nunmehr  diese  Aufrufe  und stellt sie auch
  296. in Nicht-MagiC-Umgebungen zur  Verfügung.  Einige Spezialitäten fehlen
  297. noch in BoxKite 2.00 (z.  B.  die  Filterfunktion). Ich werde sie aber
  298. noch  einbauen,  wenn   sie   gewünscht   werden.   In  den  folgenden
  299. Abschnitten möchte  ich  die  Verwendung  der  FSLX-Schnittstelle kurz
  300. beschreiben (obwohl  ich  wahrscheinlich  auch  hier  längst Bekanntes
  301. wiederkäue).
  302.  
  303. Wenn Sie die FSLX-Bibliothek verwenden  möchten, müssen Sie als erstes
  304. prüfen, ob diese Aufrufe  im  aktuellen  System vorhanden sind. Hierzu
  305. wird der aufruf 'appl_getinfo()' verwendet:
  306.  
  307.     appl_getinfo(7, &gout1, &gout2, &gout3, &gout4);
  308.     if ( (gout1 & 8) == 0 )
  309.     {   form_alert(1, "[3][ FSLX nicht vorhanden! ][   Ok   ]");
  310.         appl_exit();
  311.         return 0;
  312.     }
  313.  
  314. Die  Unterfunktion  7  von  'appl_getinfo()'  fragt  MagiC-spezifische
  315. Informationen   ab.   Im   Parameter   gout1   werden   einzelne  Bits
  316. zurückgegeben,   die    das    Vorhandensein    diverser   erweiterter
  317. Dialogbibliotheken   signalisieren.   Bit   3   ist   hier   für   die
  318. Dateiauswahlbibliothek FSLX zuständig. Dieser  Aufruf wird von BoxKite
  319. so modifiziert, da₧ das Bit 3 immer gesetzt ist.
  320.  
  321. Falls die vorhandene  TOS-Version  die Funktion 'appl_getinfo()' nicht
  322. unterstützt,  kann  auch  der  'HBFS'-Cookie  ausgewertet  werden. Die
  323. FSLX-Aufrufe sind genau dann vorhanden, wenn  der Wert des Cookies auf
  324. eine Struktur vom Typ 'BXKT_STR'  zeigt, die ein gültiges 'magic'-Wort
  325. und die Versionsnummer >= 2.00 enthält:
  326.  
  327.     BXKT_STR *value;
  328.  
  329.     if ( cookie_find('HBFS', &value) )
  330.     {   if ( value->magic == 'BxKt' && value->version >= 0x200 )
  331.         {
  332.             /* FSLX-Lib vorhanden */
  333.         }
  334.     }
  335.  
  336. BTW: Das 'Abschalten' von BoxKite  über  das  CPX-Modul wirkt sich auf
  337. die   FSLX-Aufrufe   nur   dann   aus,   wenn   das   zugrundeliegende
  338. Betriebssystem diese in  einer  eigenen  Version  zur Verfügung stellt
  339. (gilt bisher  m.  W.  nur  für  neuere  MagiC-Versionen).  Andernfalls
  340. bleiben die entsprechenden  Routinen  von  BoxKite  immer aktiv, damit
  341. diese Aufrufe nicht ins Leere gehen.
  342.  
  343.     FSLX-Dateiauswahl als Fenster
  344.     -----------------------------
  345.  
  346. Die  FSLX-Schnittstelle  behandelt   einen   Fileselector   nicht  als
  347. Dialogbox im  herkömmlichen  Sinne  mit  einer eigenen Event-Schleife,
  348. sondern bindet ihn in die  Hauptschleife  der Applikation mit ein. Das
  349. bedeutet,  da₧  die   Applikation   nach  jedem  'evnt_multi()'-Aufruf
  350. erstmal die Dateiauswahlbox fragen  mu₧,  ob  diese mit dem erhaltenen
  351. Event etwas anfangen kann.
  352.  
  353. Die Einbindung in eine Applikation könnte grob so aussehen:
  354.  
  355.     int fsel_cont;
  356.     int button, nfiles;
  357.     char name[256];
  358.     void *fsel = NULL;          /* Diese Variable nimmt das Handle */
  359.                                 /* des Fileselectors auf. */
  360.  
  361.     /* Hier sind wir in einem Unterprogramm, das z. B.
  362.        einen Menüaufruf verarbeitet ... */
  363.  
  364.     fsel = fslx_open(...);      /* Fileselector öffnen */
  365.     if ( fsel == NULL )
  366.     {
  367.         /* Fehlermeldung o. ä. */
  368.     }
  369.  
  370.     ...
  371.  
  372.     /* Hier sind wir in der Hauptschleife der Applikation... */
  373.  
  374.     event = evnt_multi(...);    /* Events abrufen */
  375.     if ( fsel != NULL )         /* Wenn ein Fileselector offen ist */
  376.     {                           /* Events an diesen abgeben */
  377.  
  378.         fsel_cont = fslx_evnt(fsel, ..., name, &button, &nfiles, ...);
  379.  
  380.         if ( fsel_cont == 0 )   /* Dateiauswahl wurde beendet */
  381.         {   if ( button )
  382.             {                   /* User hat "Ok" geklickt, also */
  383.                                 /* verarbeite gewählte Dateien */
  384.                 bearbeite_datei(name);  /* 1. Datei */
  385.  
  386.                 while ( --nfiles )      /* weitere Dateien */
  387.                 {   fslx_getnxtfile(fsel, name);
  388.                     bearbeite_datei(name);
  389.                 }
  390.             }
  391.             fslx_close(fsel);   /* Fileselector schlie₧en */
  392.             fsel = NULL;
  393.         }
  394.     }
  395.     if ( event & MU_MESAG )
  396.     {   ...
  397.  
  398.         /* Hier werden die Events für die weiteren Fenster */
  399.         /* der Applikation verarbeitet */
  400.     }
  401.  
  402. Nun folgt eine genaue  Beschreibung der verwendeten FSLX-Aufrufe:
  403.  
  404.     fslx_open()
  405.     -----------
  406.  
  407. Diese Funktion alloziert  die  nötigen  Speicherblöcke  und öffnet das
  408. Dateiauswahlfenster.
  409.  
  410. C-Prototyp:
  411.  
  412. void *fslx_open(char *title,
  413.                 int x, y, 
  414.                 int *whdl, 
  415.                 char *path, 
  416.                 int pathlen,
  417.                 char *fname, 
  418.                 int fnamelen,
  419.                 char *patterns,
  420.                 void *filter,
  421.                 char *paths,
  422.                 int sort_mode,
  423.                 int flags);
  424.  
  425. Bedeutung der Parameter:
  426.  
  427. title:      Text für die Titelzeile. Unter Multitasking-Systemen 
  428.             wird der Applikationsname vorangestellt.
  429.  
  430. x, y:       Anfangsposition. Wird für beide Werte -1 übergeben, 
  431.             so wird die Box zentriert.
  432.  
  433. whdl:       In dieser Variablen wird der Fensterhandle abgelegt.
  434.  
  435. path:       Vollständiger Pfad, beginnt mit Laufwerk und endet 
  436.             mit '\'.
  437.  
  438. pathlen:    Länge des Pfadbuffers, d. h. maximale Pfadlänge + 1 
  439.             (für EOS).
  440.  
  441. fname:      Puffer für den Dateinamen.
  442.  
  443. fnamelen:   Länge des Dateinamenpuffers, d.h. maximale Länge des 
  444.             Dateinamens + 1 (für EOS).
  445.  
  446. patterns:   Dateinamenmuster wie "*.TXT" oder "*.PRG,*.APP". 
  447.             Die alternativ anwählbaren Muster sind durch EOS 
  448.             getrennt und durch EOS, EOS abgeschlossen. Diese Muster
  449.             werden in BoxKite in das "F1"-Popup aufgenommen.
  450.  
  451. filter:     Unter MagiC: Zeiger auf eine Filterfunktion, die
  452.             Dateinamen von der Anzeige ausschlie₧en kann.
  453.             Zur Zeit in BoxKite nicht implementiert.
  454.  
  455. paths:      Pfad-"History" wie "C:\\BIN\\" usw. Die alternativ 
  456.             anwählbaren Pfade sind durch EOS getrennt und durch 
  457.             EOS, EOS abgeschlossen. Diese Pfade werden in BoxKite 
  458.             in das "F1"-Popup aufgenommen.
  459.  
  460. sort_mode:  Unter MagiC: Sortiermodus für die Anzeige. Wird von 
  461.             BoxKite zur Zeit ignoriert; hier gilt immer die vom
  462.             Anwender voreingestellte Sortierung.
  463.  
  464. flags:      Verschiedene Einstellungen:
  465.  
  466.             #define DOSMODE     1
  467.             #define NFOLLOWSLKS 2
  468.             #define GETMULTI    8
  469.  
  470.             DOSMODE: Ist dieses Bit gesetzt, so wird die Anzeige
  471.             von Dateinamen im Format 8+3 erzwungen.
  472.  
  473.             NFOLLOWSLKS: Unter MagiC werden symbolische Links 
  474.             nicht verfolgt. BoxKite ignoriert dieses Bit zur
  475.             Zeit und verfolgt die Links generell nicht.
  476.  
  477.             GETMULTI: Ist dieses Bit gesetzt, können mehrere
  478.             Dateien auf einmal ausgewählt und übergeben
  479.             werden. Dazu wird 'fslx_getnxtfile()' verwendet, 
  480.             wenn 'fslx_evnt()' bzw. 'fslx_do()' im Parameter 
  481.             'nfiles' signalisieren, da₧ noch weitere Dateien 
  482.             selektiert sind.
  483.  
  484. Der Rückgabewert von 'fslx_open()'  ist  der Handle des Fileselektors,
  485. der bei allen nachfolgenden  Aufrufen  zu verwenden ist. Im Fehlerfall
  486. wird der Wert NULL zurückgegeben.
  487.  
  488. Belegung der AES-Arrays:
  489.  
  490.         contrl[0] = 190        Funktionsnummer
  491.         contrl[1] = 6          Einträge in intin
  492.         contrl[2] = 1          Einträge in intout
  493.         contrl[3] = 6          Einträge in addrin
  494.         contrl[4] = 1          Einträge in addrout
  495.  
  496.         intin[0] = x
  497.         intin[1] = y
  498.         intin[2] = pathlen
  499.         intin[3] = fnamelen
  500.         intin[4] = sort_mode
  501.         intin[5] = flags
  502.  
  503.         addrin[0] = title
  504.         addrin[1] = path
  505.         addrin[2] = fname
  506.         addrin[3] = patterns
  507.         addrin[4] = filter
  508.         addrin[5] = paths
  509.  
  510.         intout[0] = whdl
  511.  
  512.         addrout[0] = Returnwert
  513.  
  514.     fslx_evnt()
  515.     -----------
  516.  
  517. Diese Funktion übergibt Events an ein Dateiauswahlfenster. Wenn dieses
  518. ein  Ereignis  verarbeitet,  so  wird  das  entsprechende  Bit  in der
  519. Eventmaske gelöscht.
  520.  
  521. C-Prototyp:
  522.  
  523. int fslx_evnt(void *fsel, 
  524.               EVNT *events, 
  525.               char *path, 
  526.               char *fname,
  527.               int *button, 
  528.               int *nfiles, 
  529.               int *sort_mode, 
  530.               char **pattern);
  531.  
  532. Bedeutung der Parameter:
  533.  
  534. fsel:       Handle des Dateiauswahlfensters, Rückgabewert 
  535.             von 'fslx_open()'.
  536.  
  537. events:     Zeiger auf eine Struktur mit Daten über den Event:
  538.  
  539.             typedef struct
  540.             {   int     mwhich;     /* Eventmaske */
  541.                 int     mx;         /* Mausposition - x */
  542.                 int     my;         /* Mausposition - y */
  543.                 int     mbutton;    /* Maustasten */
  544.                 int     kstate;     /* Shifttasten */
  545.                 int     key;        /* Tastencode */
  546.                 int     mclicks;    /* Mausklicks */
  547.                 int     reserved[9];
  548.                 int     msg[16];    /* Messagebuffer */
  549.             }
  550.             EVNT;
  551.  
  552.             Diese Struktur kann mit den Rückgabewerten aus
  553.             'evnt_multi()' gefüllt werden. Wird ein Event
  554.             vom Fileselector verarbeitet, wird das entsprechende
  555.             Bit in 'mwhich' gelöscht.
  556.  
  557. path:       Zeiger auf den ausgewählten Pfad, wenn der Dialog 
  558.             per Klick auf den OK-Button oder per Doppelklick
  559.             auf eine Datei beendet wurde.
  560.  
  561. fname:      Zeiger auf den ausgewählten Namen, wenn der Dialog 
  562.             per Klick auf den OK-Button oder per Doppelklick
  563.             auf eine Datei beendet wurde.
  564.  
  565. button:     Ist 1, wenn der Dialog per Klick auf den OK-Button oder 
  566.             per Doppelklick auf eine Datei beendet wurde. Ist 0, 
  567.             wenn der Dialog per Klick auf "Abbruch" beendet wurde.
  568.  
  569. nfiles:     Die Anzahl der selektierten Dateien (siehe Aufrufschema).
  570.  
  571. sort_mode:  Hier wird der letzte Sortiermodus abgelegt.
  572.  
  573. pattern:    Hier wird ein Zeiger auf die letzte benutzte Maske
  574.             abgelegt. Da es bei BoxKite möglich ist, eine Maske
  575.             auszuwählen, die nicht im Parameter 'patterns' von
  576.             'fslx_open()' aufgeführt ist, wird in diesem Fall
  577.             einfach der Wert dieses Parameters zurückgegeben.
  578.  
  579. Der Rückgabewert von  'fslx_evnt()'  ist  0,  wenn  der Dialog beendet
  580. werden soll (Klick auf "Ok" oder  "Abbruch" oder Doppelcklick auf eine
  581. Datei) und ansonsten 1.
  582.  
  583. Belegung der AES-Arrays:
  584.  
  585.         contrl[0] = 193        Funktionsnummer
  586.         contrl[1] = 0          Einträge in intin
  587.         contrl[2] = 4          Einträge in intout
  588.         contrl[3] = 4          Einträge in addrin
  589.         contrl[4] = 1          Einträge in addrout
  590.  
  591.         addrin[0] = fsel
  592.         addrin[1] = events
  593.         addrin[2] = path
  594.         addrin[3] = fname
  595.  
  596.         intout[0] = Returnwert
  597.         intout[1] = button
  598.         intout[2] = nfiles
  599.         intout[3] = sort_mode
  600.  
  601.         addrout[0] = pattern
  602.  
  603.     fslx_getnxtfile()
  604.     -----------------
  605.  
  606. Diese Funktion ruft nach Ende  des Dialogs weitere selektierte Dateien
  607. des Fileselektors ab.
  608.  
  609. C-Prototyp:
  610.  
  611. int fslx_getnxtfile(void *fsel, char *name);
  612.  
  613. Bedeutung der Parameter:
  614.  
  615. fsel:       Handle des Dateiauswahlfensters, Rückgabewert 
  616.             von 'fslx_open()' oder 'fslx_do()' (siehe dort).
  617.  
  618. fname:      Hier werden die gefundenen Dateinamen abgelegt.
  619.  
  620. Der Rückgabewert von  'fslx_getnxtfile()'  ist  1,  wenn  ein weiterer
  621. Dateiname zurückgegeben wurde, und ansonsten 0.
  622.  
  623. Belegung der AES-Arrays:
  624.  
  625.         contrl[0] = 192        Funktionsnummer
  626.         contrl[1] = 0          Einträge in intin
  627.         contrl[2] = 1          Einträge in intout
  628.         contrl[3] = 2          Einträge in addrin
  629.         contrl[4] = 0          Einträge in addrout
  630.  
  631.         addrin[0] = fsel
  632.         addrin[1] = fname
  633.  
  634.         intout[0] = Returnwert
  635.  
  636.     fslx_close()
  637.     ------------
  638.  
  639. Diese Funktion schlie₧t den Fileselektor und gibt die dadurch belegten
  640. Systemresourcen frei. Sie  darf  erst  dann  benutzt  werden, wenn die
  641. gewünschten Dateien mit 'fslx_getnxtfile()' abgerufen worden sind.
  642.  
  643. C-Prototyp:
  644.  
  645. int fslx_close(void *fsel);
  646.  
  647. Bedeutung des Parameters:
  648.  
  649. fsel:       Handle des Dateiauswahlfensters, Rückgabewert 
  650.             von 'fslx_open()' oder 'fslx_do()' (siehe dort).
  651.  
  652. Der  Rückgabewert  von   'fslx_close()'   ist   0,   wenn  ein  Fehler
  653. festgestellt wurde.
  654.  
  655. Belegung der AES-Arrays:
  656.  
  657.         contrl[0] = 191        Funktionsnummer
  658.         contrl[1] = 0          Einträge in intin
  659.         contrl[2] = 1          Einträge in intout
  660.         contrl[3] = 1          Einträge in addrin
  661.         contrl[4] = 0          Einträge in addrout
  662.  
  663.         addrin[0] = fsel
  664.  
  665.         intout[0] = Returnwert
  666.  
  667.     FSLX-Dateiauswahl als Dialog
  668.     ----------------------------
  669.  
  670. Für  die  Eiligen  unter  Ihnen  besteht  auch  die  Möglichkeit,  den
  671. FSLX-Fileselector als gewöhnliche Dialogbox  aufzurufen, ohne auf alle
  672. erweiterten Features verzichten zu müssen.  Das grobe Aufrufschema für
  673. diese Variante sieht so aus:
  674.  
  675.     int button, nfiles;
  676.     char name[256];
  677.     void *fsel = NULL;          /* Diese Variable nimmt das Handle */
  678.                                 /* des Fileselectors auf. */
  679.  
  680.     /* Fileselector öffnen und Dialog abhandeln */
  681.     fsel = fslx_do(..., name, ..., &button, &nfiles, ...);
  682.  
  683.     if ( fsel != NULL )         /* Wenn die Box sich öffnen lie₧ */
  684.     {   if ( button )
  685.         {                       /* User hat "Ok" geklickt, also */
  686.                                 /* verarbeite gewählte Dateien */
  687.              bearbeite_datei(name);  /* 1. Datei */
  688.  
  689.              while ( --nfiles )      /* weitere Dateien */
  690.              {   fslx_getnxtfile(fsel, name);
  691.                  bearbeite_datei(name);
  692.              }
  693.          }
  694.          fslx_close(fsel);      /* Fileselector schlie₧en */
  695.     }
  696.  
  697. Hierfür wird nur eine weitere Funktion benötigt, die den ganzen Dialog
  698. durchführt:
  699.  
  700.     fslx_do()
  701.     ---------
  702.  
  703. Diese Funktion öffnet die Dateiauswahlbox  als Dialogbox und übernimmt
  704. die  ganze  Dialogverarbeitung  in  einer  eigenen  Eventschleife. Sie
  705. endet erst dann, wenn der  User  eine  Datei ausgewählt oder "Abbruch"
  706. angeklickt hat.
  707.  
  708. C-Prototyp:
  709.  
  710. void *fslx_do(char *title,
  711.               char *path, 
  712.               int pathlen,
  713.               char *fname, 
  714.               int fnamelen,
  715.               char *patterns,
  716.               void *filter,
  717.               char *paths,
  718.               int *sort_mode,
  719.               int flags
  720.               int *button,
  721.               int *nfiles,
  722.               char **pattern);
  723.  
  724. Bedeutung der Parameter:
  725.  
  726. title:      Text für die Titelzeile. Unter Multitasking-Systemen 
  727.             wird der Applikationsname vorangestellt.
  728.  
  729. path:       Vollständiger Pfad, beginnt mit Laufwerk und endet 
  730.             mit '\'.
  731.  
  732. pathlen:    Länge des Pfadbuffers, d. h. maximale Pfadlänge + 1 
  733.             (für EOS).
  734.  
  735. fname:      Puffer für den Dateinamen.
  736.  
  737. fnamelen:   Länge des Dateinamenpuffers, d.h. maximale Länge des 
  738.             Dateinamens + 1 (für EOS).
  739.  
  740. patterns:   Dateinamenmuster wie "*.TXT" oder "*.PRG,*.APP". 
  741.             Die alternativ anwählbaren Muster sind durch EOS 
  742.             getrennt und durch EOS, EOS abgeschlossen. Diese Muster
  743.             werden in BoxKite in das "F1"-Popup aufgenommen.
  744.  
  745. filter:     Unter MagiC: Zeiger auf eine Filterfunktion, die
  746.             Dateinamen von der Anzeige ausschlie₧en kann.
  747.             Zur Zeit in BoxKite nicht implementiert.
  748.  
  749. paths:      Pfad-"History" wie "C:\\BIN\\" usw. Die alternativ 
  750.             anwählbaren Pfade sind durch EOS getrennt und durch 
  751.             EOS, EOS abgeschlossen. Diese Pfade werden in BoxKite 
  752.             in das "F1"-Popup aufgenommen.
  753.  
  754. sort_mode:  Unter MagiC: Sortiermodus für die Anzeige. Wird von 
  755.             BoxKite zur Zeit ignoriert; hier gilt immer die vom
  756.             Anwender voreingestellte Sortierung. Bei 'fslx_do()'
  757.             als Zeiger zu übergeben; hier wird nach dem Aufruf wie
  758.             bei 'fslx_evnt()' der aktuelle Sortiermodus zurück-
  759.             gegeben.
  760.  
  761. flags:      Verschiedene Einstellungen, wie bei 'fslx_open()'.
  762.  
  763. button:     Ist 1, wenn der Dialog per Klick auf den OK-Button oder 
  764.             per Doppelklick auf eine Datei beendet wurde. Ist 0, 
  765.             wenn der Dialog per Klick auf "Abbruch" beendet wurde.
  766.  
  767. nfiles:     Die Anzahl der selektierten Dateien (siehe Aufrufschema).
  768.  
  769. pattern:    Hier wird ein Zeiger auf die letzte benutzte Maske
  770.             abgelegt. Da es bei BoxKite möglich ist, eine Maske
  771.             auszuwählen, die nicht im Parameter 'patterns'
  772.             aufgeführt ist, wird in diesem Fall einfach der Wert 
  773.             dieses Parameters zurückgegeben.
  774.  
  775. Der Rückgabewert von 'fslx_do()' ist der Handle des Fileselektors, der
  776. bei allen nachfolgenden Aufrufen zu  verwenden ist. Im Fehlerfall wird
  777. der Wert NULL zurückgegeben.
  778.  
  779. Belegung der AES-Arrays:
  780.  
  781.         contrl[0] = 194        Funktionsnummer
  782.         contrl[1] = 4          Einträge in intin
  783.         contrl[2] = 4          Einträge in intout
  784.         contrl[3] = 6          Einträge in addrin
  785.         contrl[4] = 2          Einträge in addrout
  786.  
  787.         addrin[0] = title
  788.         addrin[1] = path
  789.         addrin[2] = fname
  790.         addrin[3] = patterns
  791.         addrin[4] = filter
  792.         addrin[5] = paths
  793.  
  794.         intin[0] = pathlen
  795.         intin[1] = fnamelen
  796.         intin[2] = sort_mode
  797.         intin[3] = flags
  798.  
  799.         intout[0] = 1
  800.         intout[1] = button
  801.         intout[2] = nfiles
  802.         intout[3] = sort_mode
  803.  
  804.         addrout[0] = Returnwert
  805.         addrout[1] = pattern
  806.  
  807.     Systemglobale Einstellungen
  808.     ---------------------------
  809.  
  810. Der Aufrug  'fslx_set_flags()'  dient  unter  MagiC  dazu, systemweite
  811. Einstellungen an den Fileselector zu  übergeben. Da die entsprechenden
  812. Einstellungen in BoxKite z.  Zt.  noch  nicht implementiert sind, wird
  813. dieser Aufruf von BoxKite ignoriert.
  814.  
  815. C-Prototyp:
  816.  
  817. int fslx_set_flags(int flags, int *oldval);
  818.  
  819. Belegung der AES-Arrays:
  820.  
  821.         contrl[0] = 195        Funktionsnummer
  822.         contrl[1] = 2          Einträge in intin
  823.         contrl[2] = 2          Einträge in intout
  824.         contrl[3] = 0          Einträge in addrin
  825.         contrl[4] = 0          Einträge in addrout
  826.  
  827.         intin[0] = 0
  828.         intin[1] = flags
  829.  
  830.         intout[0] = Returnwert
  831.         intout[1] = oldval
  832.  
  833.  
  834.  
  835.