home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 3 / goldfish_volume_3.bin / files / util / blank / blitzblank / developer / programmierer.dok < prev   
Encoding:
Text File  |  1995-05-15  |  27.9 KB  |  760 lines
  1. Anleitung zum Programmieren von Modulen für BlitzBlank 2.50
  2. ===========================================================
  3.  
  4.  0. Vorwort
  5.  1. Anforderungen an Module
  6.  2. Einleitung
  7.  3. Aufbau der GUI
  8.  4. Beschreibung der GUI-Objekte
  9.  5. Kommunikation mit BlitzBlank/BlitzBlankPrefs
  10.  6. Erklärung der Flags
  11.  7. Beschreibung der BlitzBlank-Strukturen und Flags
  12.  8. Beschreibung der globalen Definitionen eines Moduls (Beispiel)
  13.  9. Genaue Beschreibung des Hauptprogramms (Beispiel)
  14. 10. Genaue Beschreibung von blank()
  15. 11. Hinweise zur Unterstützung der locale.library
  16. 12. AmigaGuide-Anleitung für die Module
  17. 13. Tips & Tricks
  18.  
  19.  
  20. 0. Vorwort
  21. ----------
  22.  
  23. Da ich nicht alles selbst programmieren kann, habe ich versucht, das
  24. Programmieren von Modulen so einfach, wie möglich zu machen. Ich bitte
  25. allerdings die potentiellen Modulprogrammierer darum, mir mitzuteilen, wenn
  26. sie an einem Modul anfangen, damit nicht 2 Leute das gleiche programmieren.
  27. Desweiteren bekommen sie von mir ja auch die Nummern der Locale-Strings
  28. zugeteilt. Wenn ein Modul fertig ist, dann möchte ich nicht, daß der
  29. Programmierer es auf eigene Faust veröffentlicht, sondern es mir schickt.
  30. Ich baue dann seine gewünschten Texte in BlitzBlank.catalog ein und seine
  31. Anleitung in BlitzBlank.guide, um es dann zusammen mit BlitzBlank
  32. oder als Update für die letzte BlitzBlank-Version zu releasen.
  33.  
  34. Da BlitzBlank selbst keine Shareware ist, können auch die Module
  35. keine Shareware sein. Sie können höchstens zu Card- oder Giftware
  36. deklariert werden.
  37.  
  38. Was ein Modul-Autor in seinen Info-Requester schreibt (zB Adresse etc.)
  39. bleibt ihm selbst überlassen, sollte aber etwa die Form meiner Module
  40. haben.
  41.  
  42. Ich hätte (mindestens ;-) ) noch gerne folgende Module:
  43. - Flying irgendwas (Toaster etc)
  44. - irgendwas mit 3D-Grafik
  45. - Maze (Labyrinth)
  46. - Starfield
  47. - ASwarm
  48. - Fraktale
  49. - sonstige Gags
  50.  
  51. Viel Spaß,
  52.           Thomas Börkel
  53.  
  54.  
  55. 1. Anforderungen an Module
  56. --------------------------
  57.  
  58. - OS 2.x/3.x kompatibel
  59. - Minimal-OS: V2.04
  60. - keine Abschaltung des Multitaskings
  61. - AGA-kompatibel
  62. - kompatibel zu Grafikkarten, wenn möglich
  63. - möglichst Auflösungs- und Farbanzahlunabhängig
  64. - Einhaltung der beschriebenen Richtlinien
  65. - zum Doublebuffering nur EINEN Screen verwenden, aber mehrere BitMaps
  66. - möglichst keinen eigenen Screen öffnen, sondern einen von BB geben lassen
  67. - Benutzung der blitzblank.library
  68. - wenn das Modul Grafikdaten, oder ähnliches braucht, dann sollte es diese
  69.   von Platte nachladen (mittels Read() oder der iff.library), sodass das
  70.   Modul selbst möglichst klein bleibt (beim Konfigurieren zB braucht man
  71.   nämlich diese Grafikdaten nicht)
  72.  
  73.  
  74. 2. Einleitung
  75. -------------
  76.  
  77. Module für BlitzBlank sind relativ leicht zu programmieren, da BlitzBlank
  78. vieles für die Module zur Verfügung stellt. Somit kann sich der
  79. Modul-Programmierer auf das eigentliche Modul konzentrieren.
  80.  
  81. BlitzBlank/BlitzBlankPrefs verwalten die GUI, die Konfigdaten und den
  82. Screen für das Modul.
  83.  
  84. Modulnamen beginnen mit "BB." und haben keinen weiteren "." im Namen.
  85. Datenfiles für die Module (wenn es welche braucht) müssen das Format
  86. "BB.Modulname.*" haben.
  87.  
  88. BlitzBlank-Module sind zunächst einmal normale CLI-Programme, die von
  89. BlitzBlank oder BlitzBlankPrefs gestartet und im BLANK-Fall mit CTRL-C
  90. beendet werden.
  91.  
  92. Ein Modul besteht mindestens aus 2 Funktionen:
  93. - Hauptroutine (entscheidet den Programmablauf anhand des 1. Arguments)
  94. - blank()-Routine (die eigentliche Blank-Routine)
  95.  
  96. Die Module kommunizieren mittels der blitzblank.library mit BlitzBlank
  97. und BlitzBlankPrefs. Die Befehle der Library fangen alle mit "BBL_"
  98. an.
  99.  
  100. Die Module bekommen beim Start bis zu 3 Kommandozeilen-Parameter:
  101. - Aktionsschlüsselwort (BLANK|CONFIG|INFO)
  102. - Name der Ports, mit dem das Modul kommunizieren soll
  103. - Adresse der BlitzBlank Screeninfo-Struktur
  104.  
  105. Das Schlüsselwort legt fest, was das Modul zu tun hat. Beispiel einer
  106. Abfrage dafür in C:
  107.  
  108. if (strcmp (argv[1],"BLANK")==0)
  109. {
  110.   StrToLong (argv[3],(long *) &screeninfo);
  111.   BBL_SendMessage (&message,argv[2]);
  112.   if (screeninfo->bbscreen)
  113.     blank ();
  114.   BBL_ModuleDone ();
  115. }
  116. else
  117.   if (strcmp (argv[1],"CONFIG")==0)
  118.   {
  119.     BBL_SendMessage (&message,argv[2]);
  120.   }
  121.   else
  122.   {
  123.     message.first=NULL;
  124.     BBL_SendMessage (&message,argv[2]);
  125.   }
  126.  
  127. Das erste Argument wird auf BLANK|CONFIG|INFO überprüft und entsprechend
  128. folgendermaßen verfahren:
  129.  
  130. BLANK:
  131. Argument 3 wird mit der OS-Routine StrToLong() in eine Zahl verwandelt und
  132. einem Zeiger auf eine BB_Screeninfo-Struktur zugewiesen. Dann wird
  133. BBL_SendMessage (&message,argv[2]) aufgerufen. Anschließend wird die
  134. blank()-Funktion aufgerufen, die die eigentlichen Modul-Routinen enthält.
  135. Falls ein Screen angefordert wurde, muß vor diesem Aufruf noch überprüft
  136. werden, ob screeninfo->bbscreen nicht NULL ist (könnte durch Speichermangel
  137. passieren). Direkt vor der Hauptschleife in der blank()-Funktion wird
  138. auf CTRL-C abgefragt und dann BBL_ModuleRunning() aufgerufen.
  139. Nach dem Blanken muss auf JEDEN Fall BBL_ModuleDone() aufgerufen werden.
  140.  
  141. CONFIG:
  142. Argument 3 kann mit der OS-Routine StrToLong() in eine Zahl verwandelt und
  143. einem Zeiger auf eine BB_Screeninfo-Struktur zugewiesen werden.
  144. BBL_SendMessage (&message,argv[2]) wird aufgerufen.
  145. Wenn ein Modul BBF_Screenmode setzt und BBF_Colors nicht und im
  146. Screeninfo die depth setzt, dann zeigt der Screenmoderequester in BBPrefs
  147. auch nur die Modes an, die über mindestens diese Tiefe verfügen.
  148.  
  149. INFO:
  150. Der Zeiger auf das erste GUI-Objekt wird auf NULL gesetzt. Dann wird
  151. BBL_SendMessage (&message,argv[2]) aufgerufen.
  152.  
  153.  
  154. 3. Aufbau der GUI
  155. -----------------
  156.  
  157. Die grafische Oberfläche eines BB-Moduls wird durch GUI-Objekte
  158. beschrieben. Das Verwalten der Oberfläche und das Speichern und Laden der
  159. Konfiguration übernimmt BlitzBlank bzw BlitzBlankPrefs. Das Modul braucht
  160. sich darum nicht zu kümmern. GUI-Objekte beschreiben also einerseits
  161. den Aufbau der GUI und sind andererseits auch gleich der Speicher
  162. für die Parameter (Konfiguration des Moduls).
  163.  
  164. An GUI-Objekten gibt es Checkmark, Stringgadget, Filegadget, Slider,
  165. Cycle-Gadget, VGroup und PGroup.
  166.  
  167. Die GUI-Objekte werden in VGroups und evt. in PGroups zusammengefaßt. Eine
  168. VGroup startet durch ein GUI-Objekt des Typs BB_VGroup und endet durch
  169. BB_VGroup_End. VGroups können nochmal zu PGroups zusammengefaßt werden.
  170. Eine Modul-GUI enthält mindestens eine VGroup. VGroups und PGroups dürfen
  171. sich NICHT(!) in Gruppen des jeweils gleichen Typs befinden.
  172.  
  173. Die GUI-Objekte (BB_Object) sind eine einfach verkettete, NULL-terminierte
  174. Liste. Da zur Zeit alle GUI-Objekte gleich groß sind, kann man zu diesem
  175. Zweck einfach ein Array vom Typ BB_Object anlegen und die Array-Elemente
  176. entsprechend verketten (Feld <next> zeigt auf das nächste Objekt oder NULL
  177. beim letzten).
  178.  
  179. Die einzelnen Felder der Objekte (zB <set>, <contents>...) müssen vom
  180. Modul vorbelegt werden mit Standardeinstellungen, bevor die Message
  181. abgeschickt wird. Wenn im BLANK-Fall die Message zurückkommt, kann
  182. das Modul aus den GUI-Objekten die tatsächlich gewählten Parameter
  183. auslesen.
  184.  
  185. Eine VGroup ist eine vertikale Gruppe von Gadgets. Die Gadgets werden in
  186. der GUI untereinander dargestellt. Wenn eine Modul-GUI mehrere VGroups
  187. besitzt, dann werden die vertikalen Gruppen nebeneinander dargestellt.
  188.  
  189. Eine PGroup enthält mehrere VGroups. Diese können mit einem Cycle-Gadget
  190. oder einem Register-Gadget (je nachdem, wie MUI eingestellt ist),
  191. umgeschaltet werden.
  192.  
  193. Eine Oberfläche könnte beispielsweise so aufgebaut sein:
  194. BB_VGroup->BB_Slider->BB_Slider->BB_VGroup_End->BB_VGroup->BB_Check->
  195. BB_Check->BB_VGroup_End
  196.  
  197. Diese GUI hätte 2 Spalten. In der linken Spalte wären 2 Slider, in der
  198. rechten Spalte 2 Checkmarks. Mehr Beispiele findet man bei den beigelegten
  199. Modul-Sourcecodes.
  200.  
  201.  
  202. 4. Beschreibung der GUI-Objekte
  203. -------------------------------
  204.  
  205. Man kann bei den Labels der GUI-Objekte einen Unterstrich "_" vor einen
  206. Buchstaben stellen, um diesen zur Taste für die Tastatursteuerung zu
  207. machen. Allerdings dürfen die Buchstaben A, C, I, P, S, T nicht benutzt
  208. werden, da diese für die unteren Buttons benötigt werden. Die Labels
  209. werden im Sourcecode in englisch definiert.
  210.  
  211. Es folgt die Beschreibung der möglichen GUI-Objekte. Namen in <> sind
  212. Konstanten oder Felder in BB_Object.
  213.  
  214. Pagegroup:
  215. Start durch <BB_PGroup>, Ende durch <BB_PGroup_End>.
  216. In <set> steht die voreingestellte Page-Nummer, <label> zeigt auf ein
  217. NULL-terminiertes Stringsarray mit den Überschriften für die Pages.
  218.  
  219. Verticalgroup:
  220. Start durch <BB_VGroup>, Ende durch <BB_VGroup_End>.
  221. Falls <label> nicht NULL ist, muß <label> auf einen String zeigen. In
  222. diesem Fall hat die VGroup eine Überschrift und einen Rahmen.
  223.  
  224. Checkmark-Gadget:
  225. Erkennung durch <BB_Check>.
  226. <set> kennzeichnet den Status, <label> zeigt auf den Labeltext.
  227.  
  228. Stringgadget:
  229. Erkennung durch <BB_String>.
  230. <max> ist die maximale Anzahl Zeichen, die das Stringgadget zulassen soll,
  231. <contents> zeigt auf einen String-Buffer dafür, den DAS MODUL allokieren
  232. muß, <label> zeigt auf den Labeltext.
  233.  
  234. Filegadget:
  235. Erkennung durch <BB_File>.
  236. <max> ist die maximale Anzahl Zeichen, die das Stringgadget zulassen soll,
  237. <contents> zeigt auf einen String-Buffer dafür, den DAS MODUL allokieren
  238. muß, <label> zeigt auf den Labeltext. Neben dem Stringgadget ist
  239. ein Popbutton für einen Filerequester.
  240.  
  241. Directorygadget:
  242. Erkennung durch <BB_Dir>.
  243. Entspricht BB_File, erlaubt aber nur Selektion von Directories.
  244.  
  245. Fontgadget:
  246. Erkennung durch <BB_Font>.
  247. <max> ist die maximale Anzahl Zeichen, die das Stringgadget zulassen soll,
  248. <contents> zeigt auf einen String-Buffer dafür, den DAS MODUL allokieren
  249. muß, <label> zeigt auf den Labeltext. Neben dem Stringgadget ist
  250. ein Popbutton für einen Fontrequester.
  251.  
  252. Slider:
  253. Erkennung durch <BB_Slider>.
  254. <min> und <max> sind die Grenzen des Sliders, <set> der voreingestellte
  255. Wert, <label> zeigt auf den Labeltext.
  256.  
  257. Cyclegadget:
  258. Erkennung durch <BB_Cycle>.
  259. <set> kennzeichnet die angewählte Option, <contents> zeigt auf ein
  260. NULL-terminiertes Stringarray mit den Optionen, <label> zeigt auf den
  261. Labeltext.
  262.  
  263. Dummyobjekt:
  264. Erkennung durch <BB_Dummy>.
  265. Dieses Objekt wird als einziges verwendet, wenn das Modul keinerlei
  266. Einstellungsmöglichkeiten durch GUI-Objekte anbieten will.
  267.  
  268.  
  269. 5. Kommunikation mit BlitzBlank/BlitzBlankPrefs
  270. -----------------------------------------------
  271.  
  272. Wenn das Modul gestartet wird, erhält es auch
  273. einen Zeiger auf die BlitzBlank-Screeninfo-Struktur. Hier kann das Modul
  274. abweichende Screenparameter festlegen. ZB könnte ein Modul <width> auf 100
  275. setzen. Dadurch bekäme es einen 100 Pixel breiteren Screen, als der
  276. Benutzer eingestellt hat. In der Screeninfo-Struktur kann das Modul <xpos>,
  277. <ypos>, <width> und <height> vorbelegen. Dieser Werte addiert BlitzBlank
  278. dann zu den vom Benutzer ausgewählten Werten. Im NORMALfall wird ein Modul
  279. nichts in diese Struktur hineinschreiben müssen, es sei denn, es will
  280. zB einen Screen von BlitzBlank haben, aber die Tiefe immer selbst
  281. festlegen (BBF_Colors wäre dann nicht gesetzt). In dem Fall würde
  282. das Modul VOR dem Aufruf von BBL_SendMessage() die Tiefe nach
  283. screeninfo->depth schreiben. Außerdem kann das Modul in <mindepth>
  284. und <maxdepth> die Tiefe des Screens eingrenzen, wenn es will. BlitzBlank,
  285. sowie der Screenmode-Requester von BBPrefs halten sich dann an diese
  286. Grenzen.
  287.  
  288. Das Modul sendet durch BBL_SendMessage() dann eine Message an
  289. BlitzBlank/BlitzBlankPrefs, nachdem es die Flags in <flags>, den Infotext
  290. in <infotext> und (wenn Schlüsselwort!=INFO) in <first> den Zeiger auf das
  291. erste GUI-Objekt gesetzt hat.
  292. Die GUI-Objekte müssen mit den voreingestellten Parametern gefüllt sein.
  293. Wenn die Funktion zurückkommt, sind die Felder <modpri> und <path>
  294. gefüllt. <modpri> ist die eingestellte Modul-Taskpriorität (wird später in
  295. blank() gesetzt) und <path> ist der Pfad zu den Modulen, falls ein Modul
  296. noch eigene Daten nachladen will findet es diese dort (Namensmuster für
  297. extra Moduldaten: "BB.Modulname.*"). Auch ist nach BBL_SendMessage()
  298. die Screeninfo-Struktur ausgefüllt und ein Screen ist für das Modul
  299. bereitgestellt worden (außer, es wollte keinen). Die GUI-Objekte sind
  300. dann mit den vom Benutzer eingestellten Werten gefüllt und können
  301. ausgelesen werden.
  302.  
  303. Folgendes passiert dann alles in blank():
  304. Das Modul sollte sodann sämtliche Vorberechnungen ausführen, evt. Daten
  305. nachladen, evt. Speicher allokieren etc. Dann bringt es seinen Screen
  306. mit ScreenToFront (screeninfo->bbscreen) in den Vordergrund, prüft
  307. ob mittlerweile ein CTRL-C ankam und ruft dann BBL_ModuleRunning() auf.
  308. Schließlich kann die Hauptaktion des Modules starten. Hier werden
  309. die eingestellten Parameter aus den GUI-Objekten ausgelesen. Das Modul muß
  310. auf einen Abbruch durch CTRL-C reagieren können. In diesem Fall gibt das
  311. Modul alles wieder frei (außer dem Screen, wenn es kein eigener war) und
  312. ruft dann BBL_ModuleDone() auf. Damit ist das Modul dann beendet.
  313. Falls das Modul von BlitzBlank keinen Screen bekommt, obwohl es einen
  314. möchte (screeninfo->bbscreen==NULL), oder aus Speicherplatzmangel
  315. keine Variablen anlegen kann, dann sollte das Modul sofort BBL_ModuleDone()
  316. aufrufen und sich danach beenden.
  317.  
  318.  
  319. 6. Erklärung der Flags
  320. ----------------------
  321.  
  322. BBF_Screenmode    : Das Modul erlaubt Screenmode-Auswahl
  323. BBF_Colors        : Das Modul erlaubt Farbanzahl-Auswahl
  324. BBF_Sample        : Noch nicht implementiert
  325. BBF_NoWatch       : Das Modul verbraucht keine(!) CPU-Zeit
  326. BBF_NoScreen      : Das Modul will von BlitzBlank keinen Screen
  327. BBF_FirstScreen   : Das Modul will die Daten der vordersten Screens
  328. BBF_CloneScreen   : Das Modul will eine Kopie des vordersten Screens
  329. BBF_AmigaOnly     : Das Modul ist NICHT kompatibel mit Grafikkarten
  330. BBF_NoMouseBlank  : Das Modul will nicht, daß die Maus geblankt wird
  331. BBF_NoKeyPass     : Das Modul benutzt keinen Screen und aktiviert auch kein Window
  332. BBF_BigWindow     : Das Blankwindow füllt den ganzen Screen aus
  333. BBF_Interleaved   : BlitzBlank vesucht, einen Screen mit Interleaved BitMap zu öffnen
  334.  
  335. Wenn ein Modul einen eigenen Screen will, (wie zB BB.Pyro), dann wird es die
  336. Flags BBF_Screenmode und BBF_Colors setzen.
  337.  
  338. Wenn ein Modul am vordersten Screen DIREKT manipuliert (wie zB BB.Fade),
  339. wird es das Flag BBF_FirstScreen setzen. Diese Art von Modulen ist mit
  340. großer Vorsicht zu genießen.
  341.  
  342. Wenn ein Modul Effekte auf einer exakten Kopie des vordersten Screens
  343. ausführt (wie zB BB.Melt), dann wird es das Flag BBF_CloneScreen setzen.
  344.  
  345. Wenn BBF_NoMouseBlank NICHT gesetzt ist, öffnet BlitzBlank ein Window
  346. auf dem jeweiligen Screen, setzt darauf einen leeren Mauszeiger
  347. (SetPointer()) und aktiviert dieses.
  348.  
  349. Hinweise:
  350. ---------
  351. Wenn ein Modul seinen Screen selbst öffnen und verwalten will
  352. (BBF_NoScreen), sollte es die Funktionen BBL_BlankMouse() und
  353. BBL_UnBlankMouse zum Mausblanken auf diesem Screen benutzen.
  354.  
  355. Zum Schließen des Screens sollte es BBL_CloseScreenSafe () benutzen.
  356.  
  357. Der Screen sollte mit dem Tag "SA_Behind,TRUE" geöffnet werden und
  358. erst kurz vor BBL_ModuleRunning() mit ScreenToFront() in den
  359. Vordergrund gebracht werden.
  360.  
  361. Außerdem sollte es mit
  362. VideoControlTags(screen->ViewPort.ColorMap,VTAG_BORDERBLANK_SET,-1,TAG_DONE);
  363. den Border seines Screens auf schwarz schalten.
  364.  
  365. Desweiteren MUSS das Modul seinen selbst geöffneten Screen in
  366. screeninfo->bbscreen eintragen!
  367.  
  368. Module, die eine Kopie des vordersten Screens anfordern (BBF_CloneScreen),
  369. können einen Screen mit mehr Planes, als der Originalscreen anfordern,
  370. wenn sie in screeninfo->depth die Differenz eintragen.
  371.  
  372.  
  373. 7. Beschreibung der BlitzBlank-Strukturen und Flags
  374. ---------------------------------------------------
  375.  
  376. #ifndef BLITZBLANK_H
  377. #define BLITZBLANK_H
  378.  
  379. #include <exec/ports.h>
  380. #include <exec/tasks.h>
  381.  
  382.  
  383. /****************************************/
  384. /* $VER: BlitzBlank.h 2.50 (01.03.95)   */
  385. /****************************************/
  386.  
  387. /********************************/
  388. /* Stuff for blitzblank.library */
  389. /********************************/
  390.  
  391. #define BLITZBLANKLIB_VER 6
  392.  
  393. extern struct BitMap   *BBL_AllocBitMap        (ULONG width,ULONG height,ULONG depth,ULONG flags);
  394. extern struct BitMap   *BBL_AllocDBufBitMap    (struct Screen *screen);
  395. extern struct RastPort *BBL_AllocRastPort      (ULONG width,ULONG height,ULONG depth,ULONG flags);
  396. extern void             BBL_BlankDone          (void);
  397. extern struct Window   *BBL_BlankMouse         (struct Screen *screen,UBYTE mode);
  398. extern void             BBL_CloseScreenSafe    (struct Screen *screen);
  399. extern BOOL             BBL_CopyOriginalColors (struct Screen *screen);
  400. extern BOOL             BBL_CopyOriginalScreen (struct Screen *screen);
  401. extern void             BBL_EndDBuf            (ULONG handle);
  402. extern BOOL             BBL_FadeDown           (struct Screen *screen,UBYTE final,UBYTE delay);
  403. extern void             BBL_FreeBitMap         (struct BitMap *bitmap);
  404. extern void             BBL_FreeRastPort       (struct RastPort *rastport);
  405. extern long             BBL_GetDarkestPen      (struct Screen *screen);
  406. extern char*            BBL_GetString          (UWORD num,char *text);
  407. extern ULONG            BBL_InitDBuf           (struct Screen *screen,struct BitMap *bitmap);
  408. extern void             BBL_ModuleRunning      (void);
  409. extern BOOL             BBL_ScreenAvailable    (struct Screen *screen);
  410. extern BOOL             BBL_SendMessage        (struct BB_Message *bbmessage,char *portname);
  411. extern void             BBL_ShowBitMap         (struct Screen *screen,struct BitMap *bitmap,ULONG handle);
  412. extern void             BBL_UnBlankMouse       (struct Window *window);
  413.  
  414.  
  415. /*******************************************************************/
  416. /* The different kinds of GUI-objects for a module's config-window */
  417. /*******************************************************************/
  418.  
  419. #define BB_PGroup     1 /* Indicates the start of a new page group */
  420. #define BB_PGroup_End 2 /* Indicates the end of the page group */
  421. #define BB_VGroup     3 /* Indicates the start of a new vertical group */
  422. #define BB_VGroup_End 4 /* Indicates the end of the vertical group */
  423. #define BB_Check      5 /* Checkmark, uses set field in BB_Object */
  424. #define BB_String     6 /* Textgadget, uses max/contents fields in BB_Object */
  425. #define BB_File       7 /* Stringgadget with attached filerequester */
  426. #define BB_Slider     8 /* Slidergadget, uses min/max/set fields in BB_Object */
  427. #define BB_Cycle      9 /* Cyclegadget, uses set/contents in BB_Object */
  428. #define BB_Dummy     10 /* Dummy, if you want no gadgets at all */
  429. #define BB_Font      11 /* Stringgadget with attached fontrequester */
  430. #define BB_Dir       12 /* Stringgadget with attached filerequester, Dirs only */
  431.  
  432. /*****************************************/
  433. /* Flags used in BB_Message's flag-field */
  434. /*****************************************/
  435.  
  436. #define BBF_Screenmode   (1L <<  0)  /* Allows screenmode-selection */
  437. #define BBF_Colors       (1L <<  1)  /* Allows screendepth-selection */
  438. #define BBF_Sample       (1L <<  2)  /* Not supported yet */
  439. #define BBF_NoWatch      (1L <<  3)  /* Eats no CPU-time, so needs no checking */
  440. #define BBF_NoScreen     (1L <<  4)  /* Wants no screen from BlitzBlank */
  441. #define BBF_FirstScreen  (1L <<  5)  /* Wants pointer to screen in front, be CAREFUL with this! */
  442. #define BBF_CloneScreen  (1L <<  6)  /* Wants a clone from the FrontScreen */
  443. #define BBF_AmigaOnly    (1L <<  7)  /* Not supported yet */
  444. #define BBF_NoMouseBlank (1L <<  8)  /* No mouseblanking from BlitzBlank wanted */
  445. #define BBF_NoKeyPass    (1L <<  9)  /* No keypassing necessary (no mouseblanking, no own active window */
  446. #define BBF_BigWindow    (1L << 10)  /* The blankwindow fills the whole screen */
  447. #define BBF_Interleaved  (1L << 11)  /* BlitzBlank TRIES to give you a screen with an Interleaved BitMap */
  448.  
  449.  
  450. /*****************************************/
  451. /* The structure, that holds config-data */
  452. /*****************************************/
  453.  
  454. struct BB_Object
  455. {
  456.   struct BB_Object* next;     /* Pointer to next object or NULL if last object */
  457.   WORD              type;     /* What kind of GUI-object this is */
  458.   long              min;      /* Minimum value for BB_Slider */
  459.   long              max;      /* Maximum value for BB_Slider, max length of BB_String */
  460.   long              set;      /* Value of BB_Slider, state of BB_Checkmark, BB_Cycle */
  461.   char             *contents; /* Pointer to buffer for BB_String, pointer to stringarray for BB_Cycle */
  462.   char             *label;    /* Label for ALL objects */
  463. };
  464.  
  465.  
  466. /*****************************************************/
  467. /* The message to send to BlitzBlank/BlitzBlankPrefs */
  468. /*****************************************************/
  469.  
  470. struct BB_Message
  471. {
  472.   struct Message    msg;        /* Normal Exec-Message-structure */
  473.   long              flags;      /* Flags for this module */
  474.   char             *infotext;   /* Pointer to infotext for this module */
  475.   struct BB_Object *first;      /* Pointer to first BB_Object or NULL for Info-action */
  476.   WORD              modpri;     /* not of use, if you use the library */
  477.   char             *path;       /* Path to directory for module-data */
  478.   struct Task      *blitzblank; /* not of use, if you use the library */
  479. };
  480.  
  481.  
  482. /***************************************/
  483. /* The BlitzBlank-Screeninfo-structure */
  484. /***************************************/
  485.  
  486. struct BB_Screeninfo
  487. {
  488.   WORD             xpos;       /* should be 0 */
  489.   WORD             ypos;       /* should be 0 */
  490.   WORD             width;      /* User-selected screen-width */
  491.   WORD             height;     /* User-selected screen-height */
  492.   WORD             depth;      /* User-selected screen-depth */
  493.   long             mode;       /* User-selected screen-mode */
  494.   struct Screen   *bbscreen;   /* module screen */
  495.   struct Window   *bbwindow;   /* blank window */
  496.   WORD             mindepth;   /* desired minimum depth or 0 */
  497.   WORD             maxdepth;   /* desired maximum depth or 0 */
  498. };
  499.  
  500.  
  501. /************************************************************/
  502. /* Flag-definition for BBL_AllocBitMap()/BBL_AllocRastPort, */
  503. /* if you don't have the V39-includes                       */
  504. /************************************************************/
  505.  
  506. #ifndef BMB_CLEAR
  507. #define BMB_CLEAR 0
  508. #define BMB_DISPLAYABLE 1
  509. #define BMB_INTERLEAVED 2
  510. #define BMF_CLEAR (1l<<BMB_CLEAR)
  511. #define BMF_DISPLAYABLE (1l<<BMB_DISPLAYABLE)
  512. #define BMF_INTERLEAVED (1l<<BMB_INTERLEAVED)
  513. #endif
  514.  
  515. #endif
  516.  
  517.  
  518. 8. Beschreibung der globalen Definitionen eines Moduls (Beispiel)
  519. -----------------------------------------------------------------
  520.  
  521. /* Einbindung der BlitzBlank-Definitionen */
  522.  
  523. #include <pragmas/blitzblank_pragmas.h>
  524. #include <BlitzBlank.h>
  525.  
  526. /* Definition der BlitzBlankBase */
  527.  
  528. struct Library *BlitzBlankBase;
  529.  
  530. /* Versionstring */
  531.  
  532. static const char version[]="$VER: BB.Melt 2.50 (26.12.94)";
  533.  
  534. /* Definition der Texte (in englisch) */
  535.  
  536. char *text[]={"\33c\33uMelt\33n\n\nModule for BlitzBlank\n\nCopyright1994\nby\nThomas Börkel",
  537.               "_Speed:",
  538.               "S_ize:"};
  539.  
  540. /* Definition der GUI-Objekte mit den Voreinstellungsparametern */
  541.  
  542. struct BB_Object object[]={ {&object[1],BB_VGroup    ,0,  0,  0,NULL,NULL},
  543.                             {&object[2],BB_Slider    ,1,150,100,NULL,NULL},
  544.                             {&object[3],BB_Slider    ,1,100, 30,NULL,NULL},
  545.                             {NULL      ,BB_VGroup_End,0,  0,  0,NULL,NULL} };
  546.  
  547.  
  548. /* Definiton der BB_Message */
  549.  
  550. struct BB_Message message;
  551.  
  552. /* Definition des Zeigers auf BB_Screeninfo */
  553.  
  554. struct BB_Screeninfo *screeninfo;
  555.  
  556.  
  557. 9. Genaue Beschreibung des Hauptprogramms (Beispiel)
  558. ----------------------------------------------------
  559.  
  560. Das Hauptprogramm sollte folgendermaßen aussehen (Beispiel in C):
  561.  
  562. void main (int argc,char **argv)
  563. {
  564.   int i;
  565.  
  566. /* Öffnen der blitzblank.library */
  567.  
  568.   if (!(BlitzBlankBase=OpenLibrary ("blitzblank.library",BLITZBLANKLIB_VER)))
  569.     exit (0);
  570.  
  571. /* Flags setzen */
  572.  
  573.   message.flags=BBF_CloneScreen;
  574.   message.first=&object[0];
  575.  
  576. /* BLANK/CONFIG/INFO? */
  577.  
  578.   if (strcmp (argv[1],"BLANK")==0)
  579.   {
  580.  
  581. /* screeninfo holen */
  582.  
  583.     StrToLong (argv[3],(long *) &screeninfo);
  584.  
  585. /* Message und GUI-Objekte ausfüllen lassen */
  586.  
  587.     BBL_SendMessage (&message,argv[2]);
  588.  
  589. /* Screen offen? */
  590.  
  591.     if (screeninfo->bbscreen)
  592.  
  593. /* Blanken */
  594.  
  595.       blank ();
  596.  
  597. /* Blankroutine beendet */
  598.  
  599.     BBL_BlankDone ();
  600.   }
  601.   else
  602.   {
  603.  
  604. /* Locale-Texte holen (200=Zahl, die vom BB-Autor zugewiesen wird) */
  605.  
  606.     message.infotext=BBL_GetString (200,text[0]);
  607.  
  608.     for (i=1;i<=5;i++)
  609.       object[i].label=BBL_GetString (200+i,text[i]);
  610.  
  611.     if (strcmp (argv[1],"CONFIG")==0)
  612.     {
  613.       BBL_SendMessage (&message,argv[2]);
  614.     }
  615.     else
  616.     {
  617.       message.first=NULL;
  618.       BBL_SendMessage (&message,argv[2]);
  619.     }
  620.   }
  621.  
  622. /* Library schließen */
  623.  
  624.   CloseLibrary (BlitzBlankBase);
  625.   exit (0);
  626. }
  627.  
  628.  
  629. 10. Genaue Beschreibung von blank()
  630. -----------------------------------
  631.  
  632. void blank (void)
  633. {
  634.  
  635. /* Vorbereitungen treffen (Speicher allokieren etc) */
  636.  
  637. /* Wenn das Modul seinen Screen selbst öffnete, muß es ihn jetzt in */
  638. /* screeninfo->bbscreen eintragen                                   */
  639.  
  640.   if (!CheckSignal (SIGBREAKF_CTRL_C))
  641.   {
  642.  
  643. /* Screen nach vorne holen */
  644.  
  645.      ScreenToFront (screeninfo->bbscreen);
  646.  
  647.      BBL_ModuleRunning (); /* Screen muß hier bereits vorne sein */
  648.  
  649. /* Hauptschleife mit Abbruchmöglichkeit durch SIGBREAKF_CTRL_C */
  650. /* Eingestellte Parameter aus den GUI-Objekten auslesen        */
  651.  
  652.   }
  653.  
  654. /* Aufräumen */
  655.  
  656.   return;
  657. }
  658.  
  659.  
  660. 11. Hinweise zur Unterstützung der locale.library
  661. -------------------------------------------------
  662.  
  663. BlitzBlank/BlitzBlankPrefs verwenden EINEN Catalog "blitzblank.catalog".
  664. Hier drin stehen die lokalisierten Strings für BlitzBlank, BlitzBlankPrefs
  665. und alle Module. Welche Strings zu dem jeweiligen Modulen gehören, legt der
  666. BlitzBlank-Autor fest. Die Modul-Programmierer sollten in ihren Programmen
  667. die englischen Texte einbauen und die passenden deutschen dazu dem Autor
  668. mitteilen. Dieser baut die Texte dann in den Catalog ein.
  669. Zur Zeit sind folgende Nummern für Texte vergeben:
  670.  
  671. 001-199: BlitzBlank/BlitzBlankPrefs
  672. 200-209: BB.Melt
  673. 210-219: BB.Fade
  674. 220-229: BB.Pyro
  675. 230-239: BB.Crumble
  676. 240-249: BB.Mosaic
  677. 250-259: BB.Aquarium
  678. 260-269: BB.Flash
  679. 270-279: BB.Lines
  680. 280-289: BB.Butterfly
  681. 290-299: BB.Slideshow
  682. 300-309: BB.Starfield
  683. 310-319: BB.Splines
  684. 320-329: BB.AmigaSign
  685. 330-339: BB.PatternCycling
  686. 340-349: BB.Execute
  687. 350-359: BB.Worms
  688. 360-379: BB.Tiles
  689. 380-399: BB.Clock
  690. 400-409: BB.Mandel
  691. 410-419: BB.Electric
  692. 420-429: BB.Fountain
  693. 430-439: BB.Guru
  694. 440-449: BB.Noise
  695. 450-459: BB.Radar
  696. 460-469: BB.Snow
  697. 470-479: BB.Worms2
  698. 480-499: BB.Spot
  699. 500-509: BB.Life
  700. 510-519: BB.Dissolve
  701. 520-539: BB.Tunnel
  702. 540-549: BB.Gravity
  703. 550-559: BB.Skyline
  704. 560-589: BB.Text
  705. 590-599: BB.FlyingToaster
  706. 600-629: BB.Plasma
  707. 630-639: BB.TicTacToe
  708. 640-649: BB.Maze
  709. 650-659: BB.ARose
  710. 660-669: BB.Fractal
  711. 670-699: Reserved
  712. 700-709: BB.Goats
  713. 710-729: BB.ASwarm
  714.  
  715.  
  716. 12. AmigaGuide-Anleitung für die Module
  717. ---------------------------------------
  718.  
  719. Die Anleitung für die Module wird in das globale AmigaGuide-Dokument
  720. BlitzBlank.Guide mit eingebunden und wird dann beim Druck auf die
  721. HELP-Taste im jeweiligen Prefs-Window eines Moduls für dieses Modul von
  722. BlitzBlankPrefs angezeigt. Die Modul-Anleitung mit Copyright-Hinweis
  723. und Anschrift des Autors sollte dem BlitzBlank-Autor möglichst in
  724. englisch und deutsch gegeben werden, damit sie in das Guide einkopiert
  725. werden kann.
  726.  
  727.  
  728. 13. Tips & Tricks
  729. -----------------
  730.  
  731. - Wenn BlitzBlank von der Shell aus gestartet wird, erscheinen auch alle
  732.   CON-Ausgaben der Module in dieser Shell (nützlich zu Debug-Zwecken). Wird
  733.   BlitzBlank von der WB aus gestartet und das Modul macht CON-Ausgaben,
  734.   dann wirft das Modul Enforcer-Hits. Das ist normal, da die Module
  735.   beim WB-Start keinen Ausgabe-Kanal bekommen. Die Module dürfen
  736.   nur zu Debug-Zwecken CON-Ausgaben machen.
  737.  
  738. - Der ARexx-Befehl DEBUG erlaubt es, ein Modul zu starten, das dann NUR
  739.   durch den ARexx-Befehl UNBLANK oder das Beenden von BlitzBlank
  740.   gestoppt wird. Man kann also in Ruhe das Modul austesten etc.
  741.  
  742. - Am besten wird die Vorgehensweise verständlich, wenn man sich die
  743.   mitgelieferten Source-Codes anschaut.
  744.  
  745. - Module, die externe Daten brauchen, müssen diese so benennen:
  746.   "BB.Modulname.xyz".
  747.  
  748. - In der blitzblank.library befinden sich nicht nur die unbedingt
  749.   notwendigen Funktionen, sondern auch ein paar nützliche (zB auch
  750.   für Double-Buffering!).
  751.  
  752. - Man sollte bei Modulen, die Zufallsfunktionen gebrauchen, nicht
  753.   vergessen, den Seed zu setzen (zB mit der aktuellen Uhrzeit, siehe
  754.   zB BB.Lines).
  755.  
  756. - Normalerweise zeichnet man in &screeninfo->bbscreen->RastPort, was recht
  757.   schnell ist. Allerdings hat man dann kein Clipping. Um Clipping zu
  758.   benutzen, setzt man das Flag BBF_BigWindow und zeichnet dann in
  759.   screeninfo->bbwindow->RPort.
  760.