Programmer's Guide to Selectric¿ V1.02 -------------------------------------- Juli 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 k”nnen, aus dem dann Da- teien oder Objekte ausgew„hlen 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 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 : 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 */ 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 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 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 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 K”ln 30 (Germany) MausNet: Oliver Scheel @ K InterNet: Oliver_Scheel@k.maus.de It's not a trick, it's Selectric¿. ---- R„chzschreipf„ler (c) 1992 by Oliver Scheel