home *** CD-ROM | disk | FTP | other *** search
/ Vectronix 2 / VECTRONIX2.iso / FILES_01 / PAPILL22.LZH / PAPILLON / BSPMODUL / MODULE.TXT / MODULE
Text File  |  1994-11-07  |  7KB  |  142 lines
  1. Richtlinien zur Modulprogrammierung:
  2. ------------------------------------
  3.  
  4. 1)  Module müssen ihre Ein- und Ausgabearten in mod_gets und mod_sends
  5.     korrekt deklarieren und erhalten NUR diese Eingaben. Als Ausgaben
  6.     werden NUR die in mod_sends deklarierten akzeptiert, die anderen
  7.     ignoriert. Alle Bilddaten und Blöcke werden in C_BITMAP-Strukturen
  8.     verwendet. Diese Bilder liegen im GEM-Standardformat vor. Den Pixeln
  9.     werden über die RGB-Farbpalette Farben zugeordnet. Die Zuordnung ist
  10.     hier 1:1 und nicht wie beim VDI üblich "durcheinander"!
  11.  
  12. 2)  Module sollten einen möglichst sinnvolle Namen in mod_name haben.
  13.  
  14. 3)  Module dürfen KEINE Daten von Papillon freigeben oder modifizieren!
  15.     Dies ist der Job von Papillon! Zuwiederhandlungen werden vermutlich
  16.     "Bömbchen" zur Folge haben! Sie sollten statt dessen die Eingabe-
  17.     daten kopieren (mit new_bitmap und z.B. vro_cpyfm) und einen Zeiger
  18.     auf die neuen Daten liefern.
  19.  
  20. 4)  Zum Allokieren und Freigeben von Speicher bitte NUR die in den Makros
  21.     spezifizierten Routinen "malloc", "calloc" und "free" verwenden.
  22.     Andere Funktionen werden vermutlich "Bömbchen" zur Folge haben!
  23.     Module sind selbst für's Freigeben von selbstangefordertem Speicher
  24.     verantwortlich. Papillon gibt diese nach Beenden des Moduls NICHT
  25.     automatisch wieder frei. Dabei "vergessene" Speicherblöcke führen
  26.     später zu einer Fragmentierung und unnötigen Reduzierung des freien
  27.     Speicherplatzes in Papillon.
  28.  
  29. 5)  Falls der Modul-Eingabetyp M_GETS_FILE ist, wird aus dem Modul ein
  30.     Bild-Lader für Papillon, der automatisch beim Finden von Dateien mit
  31.     der Endung <file_ext> angesprochen wird. Diese Module sollten vom Typ
  32.     M_SENDS_PIC sein. Der komplette Bildname steht dann in <pic_path>.
  33.     Lader werden NUR DANN automatisch aufgerufen, wenn Papillon die ent-
  34.     sprechende Datei-Endung NICHT kennt.
  35.  
  36. 6)  Module, die einen neuen Block generieren, sollten dafür sorgen, da₧
  37.     der neue Block die gleiche Farbanzahl und die gleiche Farbpalette wie
  38.     die Eingabedaten besitzen. Ein Modul darf also z.B. nicht aus einem
  39.     S/W-Block/Bild auf einmal einen Farbblock machen! Zuwiederhandlungen
  40.     werden vermutlich zu ernsten Problemen führen. Module, die einen
  41.     Block generieren, sollten vom Typ M_GETS_PIC oder M_GETS_BLOCK sein,
  42.     da sonst eventuell kein Papillon-Bild zum Einfügen des Blockes
  43.     vorhanden sein kann!
  44.  
  45. 7)  Die reservierten Datenbereiche dürfen NICHT für eigene Zwecke
  46.     verwendet werden. Sie sind eben reserviert, und werden in Zukunft
  47.     vermutlich für erweiterte Papillon-Modulkonzepte verwendet werden.
  48.  
  49. 8)  Module können die in den Makros angegebenen AES-Funktionen verwenden. 
  50.     Andere AES-Funktionen sind NICHT in Papillon-Modulen erlaubt und führen 
  51.     vermutlich zu einem Absturz. 
  52.     Die bereitgestellten Funktionen sollten für ein brauchbares Dialog-Handling 
  53.     ausreichend sein.
  54.     Fenster öffnen etc. ist u.A. aus Redraw-Technischen Gründen verboten. 
  55.     Daher sind diese AES-Funktionen auch nicht vom Modul aus erreichbar.
  56.  
  57. 9)  Programmieren Sie Ihre Module sorgfältig! Ein Absturz des Moduls
  58.     zieht auch Papillon unweigerlich mit "ins Grab"!
  59.  
  60. 10) Für die Allokierung von Bitmaps stellt Papillon die Funktion
  61.  
  62.      int new_bitmap(C_BITMAP **bitmap, int width, int height,
  63.                     int planes, RGB *colors, int show_warning);
  64.  
  65.     zur Verfügung. In <bitmap> wird ein Zeiger auf die neue Bitmap
  66.     geliefert. <width> und <height> geben die Ausma₧e der Bitmap an.
  67.     <planes> ist die Anzahl der Farbebenen der Bitmap. In <colors>
  68.     kann man die Farbpalette der Bitmap vorgeben, aber auch NULL
  69.     übergeben, um die Systempalette zu erhalten. <show_warning>
  70.     gibt an, ob Papillon bei Speichermangel eine automatisch eine
  71.     Warnung ausgeben soll.
  72.  
  73.     Eine Rückgabe < 0 signalisiert einen Fehler. In diesem Fall darf das
  74.     Ergebnisbild natürlich NICHT verwendet werden. Bitte NIEMALS Bilder
  75.     selbst zusammenallokieren, sondern NUR new_bitmap verwenden.
  76.  
  77.     Bitmaps werden mit der Funktion
  78.  
  79.      void free_bitmap(C_BITMAP *bitmap);
  80.  
  81.     wieder freigegeben.
  82.  
  83. 11) Folgende Modul-Eingabe-Ausgabekombinationen sind erlaubt:
  84.  
  85.     Input/Output | M_SENDS_NIX | M_SENDS_PIC | M_SENDS_BLOCK |
  86.     -------------+-------------+-------------+---------------|
  87.     M_GETS_NIX   | Sinnlos     | z.B. Scantr.| Verboten!     |
  88.     M_GETS_PIC   | Druckertr.  | Bildwandler | Erlaubt       |
  89.     M_GETS_BLOCK | Druckertr.  | Erlaubt     | Blockwandler  |
  90.     M_GETS_FILE  | Sinnlos     | Bildlader   | Verboten!     |
  91.     ----------------------------------------------------------
  92.  
  93.     "Sinnlos" hei₧t übrigens nicht automatisch verboten! Auch die Verwen-
  94.     dungszwecke in obiger Tabelle sind nicht zwingend. Vielleicht haben
  95.     Sie ja auch ganz andere Ideen...
  96.  
  97. 12) Lang dauernde Operationen sollten nach Möglichkeit mit einem Rechen-
  98.     slider im Dialog angezeigt werden.
  99.  
  100. 13) Module müssen ein decompiliertes Resource verwenden. Wir haben dazu
  101.     RSC2CSRC von MAXON verwendet. Aber die RSH-Dateien von z.B. Interface
  102.     sollten (zumindest theoretisch) auch verwendbar sein. Alle Module
  103.     sollten i.a. zumindest einen rudimentären AES-Dialog (OK, Abbruch) auf-
  104.     bauen und abarbeiten. Es gibt Funktionszeiger für Radiobuttons und
  105.     Checkboxen, die Papillon für Sie generieren kann. Siehe-Demo-Module...
  106.  
  107. 14) Module sollten mit allen TOS-Versionen funktionieren oder zumindest
  108.     eine Fehlermeldung ausgeben, falls dies nicht der Fall ist.
  109.  
  110. 15) Selbstprogrammierte Module dürfen frei vertrieben werden. Falls sie
  111.     "richtig gut" sind, können Sie diese Module probeweise an ASH senden,
  112.     weil ASH eventunnel Moduldisketten für Papillon vertreiben will. Ent-
  113.     lohnung ist ggf. natürlich dann Ihre Verhandlungssache...
  114.  
  115. 16) Bei Problemen/Fragen bei der Modulprogrammierung können Sie sich an
  116.     Stefan Becker @ ZW oder Dirk Sabiwalsky @ ZW im Mausnetz wenden, falls
  117.     Sie ein Modem besitzen.
  118.  
  119. 17) Papillon-Module sind am einfachsten in Pure-C programmierbar. Theo-
  120.     retisch könnte man aber Dank cdecl-Funktionszeiger auch andere Pro-
  121.     grammiersprachen (z.B. GNU-C) verwenden. Zu beachten ist aber, da₧ die
  122.     Papillon-Module nur geladen Pexec(3,...) werden und Papillon dann in
  123.     die Module "hineinspringt". D.h. eventuelle Initialisierungen im Pro-
  124.     grammheader des Moduls werden NICHT ausgeführt und müssen vom Modul
  125.     selbst in "do_module_job" durchgeführt werden. Weiterhin sind die Ints
  126.     16 Bit breit, die Chars 8 Bit, und die Longs 32 Bit. - Eben nach den
  127.     Konventionen von Pure-C. Strings sind (wie in C üblich) 0-terminiert.
  128.  
  129. 18) Module dürfen übrigens durchaus Bilder mit mehr Farbebenen als in
  130.     sys_planes angegeben erzeugen. Diese werden dann von Papillon ggf. um-
  131.     gerastert. Verboten sind natürlich Bilder mit mehr als MAX_PLANES (8)
  132.     Farbebeben.
  133.  
  134. 19) Papillon liefert einen VDI-Handle an die Module weiter. Dieser sollte
  135.     bei Bedarf auch verwendet werden.
  136.  
  137. 20) Während der Modul-Laufzeit ist wind_update(BEG_UPDATE) schon gesetzt.
  138.  
  139. 21) Module sollten keine undokumentierten TOS-Variablen etc. verwenden.
  140.  
  141.  
  142.