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 k”nnen, aus dem dann Da- teien oder Objekte ausgew„hlen kann. Ich will jetzt aber nicht zuviel verraten. Die M”glichkeiten ----------------- Ich versuche hier mal kurz die M”glichkeiten mit Selectric¿ zu umreižen, um so einen kleinen šberblick zu verschaffen: Selectric¿ installiert einen Cookie-Jar ber den die Applikation Einstellungen vornehmen kann. Das schliežt 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ž zus„tzlich 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 Gr”že 4 nach Typ bzw. Extension 5 unsortiert Ist der Wert negativ, so wird rckw„rts sortiert (z.B. -3 fr `nach Gr”že' und `rckw„rts'). num_ext Dieser Wert gibt die Anzahl der m”glichen Preset- Extensions an. Wird von der Applikation eine andere Anzahl von Extensions bergeben, so muž dieser Wert angepažt 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 ver„ndert, 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 k”nnen (Selectric¿ spei- chert nur seine eigenen Extensions/Paths ab, die von der Applikation bergebenen k”nnen 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 ver„ndert 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 tats„chliche 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/K”hling, 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 sp„teren 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 Krahnenb„umen 52-54 50668 K”ln Deutschland email: sr@k.maus.de It's not a trick, it's Selectric¿.