Richtlinien zur Modulprogrammierung:
------------------------------------

1)  Module mssen ihre Ein- und Ausgabearten in mod_gets und mod_sends
    korrekt deklarieren und erhalten NUR diese Eingaben. Als Ausgaben
    werden NUR die in mod_sends deklarierten akzeptiert, die anderen
    ignoriert. Alle Bilddaten und Blcke werden in C_BITMAP-Strukturen
    verwendet. Diese Bilder liegen im GEM-Standardformat vor. Den Pixeln
    werden ber die RGB-Farbpalette Farben zugeordnet. Die Zuordnung ist
    hier 1:1 und nicht wie beim VDI blich "durcheinander"!

2)  Module sollten einen mglichst sinnvolle Namen in mod_name haben.

3)  Module drfen KEINE Daten von Papillon freigeben oder modifizieren!
    Dies ist der Job von Papillon! Zuwiederhandlungen werden vermutlich
    "Bmbchen" zur Folge haben! Sie sollten statt dessen die Eingabe-
    daten kopieren (mit new_bitmap und z.B. vro_cpyfm) und einen Zeiger
    auf die neuen Daten liefern.

4)  Zum Allokieren und Freigeben von Speicher bitte NUR die in den Makros
    spezifizierten Routinen "malloc", "calloc" und "free" verwenden.
    Andere Funktionen werden vermutlich "Bmbchen" zur Folge haben!
    Module sind selbst fr's Freigeben von selbstangefordertem Speicher
    verantwortlich. Papillon gibt diese nach Beenden des Moduls NICHT
    automatisch wieder frei. Dabei "vergessene" Speicherblcke fhren
    spter zu einer Fragmentierung und unntigen Reduzierung des freien
    Speicherplatzes in Papillon.

5)  Falls der Modul-Eingabetyp M_GETS_FILE ist, wird aus dem Modul ein
    Bild-Lader fr Papillon, der automatisch beim Finden von Dateien mit
    der Endung <file_ext> angesprochen wird. Diese Module sollten vom Typ
    M_SENDS_PIC sein. Der komplette Bildname steht dann in <pic_path>.
    Lader werden NUR DANN automatisch aufgerufen, wenn Papillon die ent-
    sprechende Datei-Endung NICHT kennt.

6)  Module, die einen neuen Block generieren, sollten dafr sorgen, da
    der neue Block die gleiche Farbanzahl und die gleiche Farbpalette wie
    die Eingabedaten besitzen. Ein Modul darf also z.B. nicht aus einem
    S/W-Block/Bild auf einmal einen Farbblock machen! Zuwiederhandlungen
    werden vermutlich zu ernsten Problemen fhren. Module, die einen
    Block generieren, sollten vom Typ M_GETS_PIC oder M_GETS_BLOCK sein,
    da sonst eventuell kein Papillon-Bild zum Einfgen des Blockes
    vorhanden sein kann!

7)  Die reservierten Datenbereiche drfen NICHT fr eigene Zwecke
    verwendet werden. Sie sind eben reserviert, und werden in Zukunft
    vermutlich fr erweiterte Papillon-Modulkonzepte verwendet werden.

8)  Module knnen die in den Makros angegebenen AES-Funktionen verwenden. 
    Andere AES-Funktionen sind NICHT in Papillon-Modulen erlaubt und fhren 
    vermutlich zu einem Absturz. 
    Die bereitgestellten Funktionen sollten fr ein brauchbares Dialog-Handling 
    ausreichend sein.
    Fenster ffnen etc. ist u.A. aus Redraw-Technischen Grnden verboten. 
    Daher sind diese AES-Funktionen auch nicht vom Modul aus erreichbar.

9)  Programmieren Sie Ihre Module sorgfltig! Ein Absturz des Moduls
    zieht auch Papillon unweigerlich mit "ins Grab"!

10) Fr die Allokierung von Bitmaps stellt Papillon die Funktion

     int new_bitmap(C_BITMAP **bitmap, int width, int height,
                    int planes, RGB *colors, int show_warning);

    zur Verfgung. In <bitmap> wird ein Zeiger auf die neue Bitmap
    geliefert. <width> und <height> geben die Ausmae der Bitmap an.
    <planes> ist die Anzahl der Farbebenen der Bitmap. In <colors>
    kann man die Farbpalette der Bitmap vorgeben, aber auch NULL
    bergeben, um die Systempalette zu erhalten. <show_warning>
    gibt an, ob Papillon bei Speichermangel eine automatisch eine
    Warnung ausgeben soll.

    Eine Rckgabe < 0 signalisiert einen Fehler. In diesem Fall darf das
    Ergebnisbild natrlich NICHT verwendet werden. Bitte NIEMALS Bilder
    selbst zusammenallokieren, sondern NUR new_bitmap verwenden.

    Bitmaps werden mit der Funktion

     void free_bitmap(C_BITMAP *bitmap);

    wieder freigegeben.

11) Folgende Modul-Eingabe-Ausgabekombinationen sind erlaubt:

    Input/Output | M_SENDS_NIX | M_SENDS_PIC | M_SENDS_BLOCK |
    -------------+-------------+-------------+---------------|
    M_GETS_NIX   | Sinnlos     | z.B. Scantr.| Verboten!     |
    M_GETS_PIC   | Druckertr.  | Bildwandler | Erlaubt       |
    M_GETS_BLOCK | Druckertr.  | Erlaubt     | Blockwandler  |
    M_GETS_FILE  | Sinnlos     | Bildlader   | Verboten!     |
    ----------------------------------------------------------

    "Sinnlos" heit brigens nicht automatisch verboten! Auch die Verwen-
    dungszwecke in obiger Tabelle sind nicht zwingend. Vielleicht haben
    Sie ja auch ganz andere Ideen...

12) Lang dauernde Operationen sollten nach Mglichkeit mit einem Rechen-
    slider im Dialog angezeigt werden.

13) Module mssen ein decompiliertes Resource verwenden. Wir haben dazu
    RSC2CSRC von MAXON verwendet. Aber die RSH-Dateien von z.B. Interface
    sollten (zumindest theoretisch) auch verwendbar sein. Alle Module
    sollten i.a. zumindest einen rudimentren AES-Dialog (OK, Abbruch) auf-
    bauen und abarbeiten. Es gibt Funktionszeiger fr Radiobuttons und
    Checkboxen, die Papillon fr Sie generieren kann. Siehe-Demo-Module...

14) Module sollten mit allen TOS-Versionen funktionieren oder zumindest
    eine Fehlermeldung ausgeben, falls dies nicht der Fall ist.

15) Selbstprogrammierte Module drfen frei vertrieben werden. Falls sie
    "richtig gut" sind, knnen Sie diese Module probeweise an ASH senden,
    weil ASH eventunnel Moduldisketten fr Papillon vertreiben will. Ent-
    lohnung ist ggf. natrlich dann Ihre Verhandlungssache...

16) Bei Problemen/Fragen bei der Modulprogrammierung knnen Sie sich an
    Stefan Becker @ ZW oder Dirk Sabiwalsky @ ZW im Mausnetz wenden, falls
    Sie ein Modem besitzen.

17) Papillon-Module sind am einfachsten in Pure-C programmierbar. Theo-
    retisch knnte man aber Dank cdecl-Funktionszeiger auch andere Pro-
    grammiersprachen (z.B. GNU-C) verwenden. Zu beachten ist aber, da die
    Papillon-Module nur geladen Pexec(3,...) werden und Papillon dann in
    die Module "hineinspringt". D.h. eventuelle Initialisierungen im Pro-
    grammheader des Moduls werden NICHT ausgefhrt und mssen vom Modul
    selbst in "do_module_job" durchgefhrt werden. Weiterhin sind die Ints
    16 Bit breit, die Chars 8 Bit, und die Longs 32 Bit. - Eben nach den
    Konventionen von Pure-C. Strings sind (wie in C blich) 0-terminiert.

18) Module drfen brigens durchaus Bilder mit mehr Farbebenen als in
    sys_planes angegeben erzeugen. Diese werden dann von Papillon ggf. um-
    gerastert. Verboten sind natrlich Bilder mit mehr als MAX_PLANES (8)
    Farbebeben.

19) Papillon liefert einen VDI-Handle an die Module weiter. Dieser sollte
    bei Bedarf auch verwendet werden.

20) Whrend der Modul-Laufzeit ist wind_update(BEG_UPDATE) schon gesetzt.

21) Module sollten keine undokumentierten TOS-Variablen etc. verwenden.


