home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 3 / goldfish_volume_3.bin / files / util / blank / blitzblank / developer / programmers.doc < prev    next >
Encoding:
Text File  |  1995-05-15  |  26.8 KB  |  743 lines
  1. Guide to programming modules for BlitzBlank 2.50
  2. ================================================
  3.  
  4.  0. Preface
  5.  1. Requirements for modules
  6.  2. Introduction
  7.  3. Construction of the GUI
  8.  4. Description of the GUI objects
  9.  5. Communication with BlitzBlank/BlitzBlankPrefs
  10.  6. Description of the flags
  11.  7. Description of the BlitzBlank structures and flags
  12.  8. Description of the global definitions of a module (example)
  13.  9. Exact description of the main program (example)
  14. 10. Exact description of blank()
  15. 11. Advice to support the locale.library
  16. 12. AmigaGuide documentation for the modules
  17. 13. Tips and tricks
  18.  
  19.  
  20. 0. Preface
  21. ----------
  22.  
  23. Because I can't program everything alone I have tried to make the
  24. programming of modules as easy as possible. But I have to ask the potential
  25. programmers to tell me if they start to work on a module. So I can make
  26. sure that not two people work on a similar module at the same time.
  27. On the other hand they also get the number of the locale strings from me.
  28. I also don't want anybody to publish a module on their own but to send me
  29. the module. I will then implement the necessary text in the
  30. BlitzBlank.catalog and the documentation in the BlitzBlank.guide and
  31. release it with the next BlitzBlank version or as an update.
  32.  
  33. Due to BlitzBlank being no shareware the modules can't be shareware also.
  34. They can only be card- or giftware.
  35.  
  36. What a module author writes in his info requester (eg. address, etc.) is up
  37. to him/her but should be similar to my own modules.
  38.  
  39. I'd really like to have the following modules (at least ;-) ):
  40. - Flying something (Toaster etc.)
  41. - Something with 3D graphic
  42. - Maze
  43. - Starfield
  44. - ASwarm
  45. - Fractals
  46. - Anything else that's funny
  47.  
  48. Have fun,
  49.           Thomas Börkel
  50.  
  51.  
  52. 1. Requirements for the modules
  53. -------------------------------
  54.  
  55. - OS 2.x/3.x compatible
  56. - Minimum OS: V2.04
  57. - Don't turn off the multitasking
  58. - AGA compatible
  59. - Compatible with graphic cards (if possible)
  60. - Should not rely on a special screen mode and depth (if possible)
  61. - Comply with the described guidelines
  62. - If you use double buffering do it on ONE screen but with several BitMaps
  63. - Don't try to open your own screen but get one from BB (if possible)
  64. - Use the blitzblank.library
  65.  
  66. - if the module uses graphic or similar data it should read it from the
  67.   harddisk (using Read() or the iff.library), so that the module itself
  68.   will be as small as possible (e.g. during configuration this data isn't
  69.   needed)
  70.  
  71.  
  72. 2. Introduction
  73. ---------------
  74.  
  75. It's quite easy to write modules for BlitzBlank because BlitzBlank offers
  76. very much for the modules. Because of this the programmer can concentrate
  77. on the module itself.
  78.  
  79. BlitzBlank/BlitzBlankPrefs administers the GUI, the configuration and the
  80. screen for the module.
  81.  
  82. Module names have to start with "BB." and mustn't have another "." in its
  83. name. Datafiles for the modules (if they require any) have to follow
  84. the format "BB.Modulename.*".
  85.  
  86. BlitzBlank modules are essentially ordinary CLI programs which get started
  87. from BlitzBlank or BlitzBlankPrefs. If they are running they will be
  88. stopped with a CTRL-C.
  89.  
  90. A module has to have at least 2 functions:
  91. - main program (determines the programs behaviour with the 1. argument)
  92. - blank() routine (the essential blank routine)
  93.  
  94. The modules are communicating with BlitzBlank and BlitzBlankPrefs through
  95. the blitzblank.library. The instructions in the library all start with
  96. "BBL_".
  97.  
  98. The modules get up to 3 command line parameters at start:
  99. - Action key word (BLANK|CONFIG|INFO)
  100. - Name of the module's communication port
  101. - Address of BlitzBlank's screen info structure
  102.  
  103. The key word determines what the module has to do. Example of such a
  104. routine in C:
  105.  
  106. if (strcmp (argv[1],"BLANK")==0)
  107. {
  108.   StrToLong (argv[3],(long *) &screeninfo);
  109.   BBL_SendMessage (&message,argv[2]);
  110.   if (screeninfo->bbscreen)
  111.     blank ();
  112.   BBL_ModuleDone ();
  113. }
  114. else
  115.   if (strcmp (argv[1],"CONFIG")==0)
  116.   {
  117.     BBL_SendMessage (&message,argv[2]);
  118.   }
  119.   else
  120.   {
  121.     message.first=NULL;
  122.     BBL_SendMessage (&message,argv[2]);
  123.   }
  124.  
  125. The first argument is checked for BLANK|CONFIG|INFO and proceeds as
  126. follows:
  127.  
  128. BLANK:
  129. Argument 3 will be changed to a numeral with the OS routine StrToLong() and
  130. is assigned to a pointer to a BB_Screeninfo structure. Then BBL_SendMessage
  131. (&message,argv[2]) is called. Afterwards the blank() function is called
  132. which contains the essentail module routines. If a screen was requested
  133. prior to the call it has to be checked if screeninfo->bbscreen isn't zero
  134. (could happen if low on memory). Just before the main routine in the blank()
  135. function CTRL-C has to be checked and then BBL_ModuleRunning() is started.
  136. After blanking BBL_ModuleDone() must be called in ANY case.
  137.  
  138. CONFIG:
  139. Argument 3 can be changed to a numeral with the OS routine StrToLong() and
  140. is assigned to a pointer to a BB_Screeninfo structure.
  141. BBL_SendMessage (&message,argv[2]) is called.
  142. If a module sets BBF_Screenmode, doesn't set BBF_Colors and sets depth in
  143. Screeninfo then only those modes will be displayed in the screenmode
  144. requester of BBPrefs which have at least the requested depth.
  145.  
  146. INFO:
  147. The pointer to the first GUI object is set to NULL. Then BBL_SendMessage
  148. (&message,argv[2]) is called.
  149.  
  150.  
  151. 3. Construction of the GUI
  152. --------------------------
  153.  
  154. The graphic user interface a a BB module is described with GUI objects.
  155. The administration af the GUI and the saving and loading of the
  156. configuration is done by BlitzBlank and BlitzBlankPrefs. The module doesn't
  157. have to think about this. GUI objects do describe the structure of the GUI
  158. and also represent the memory for the parameters (configuration of the
  159. module).
  160.  
  161. Available GUI objects are checkmark, stringgadget, filegadget, slider,
  162. cycle gadget, VGroup and PGroup.
  163.  
  164. The GUI objects are compiled in VGroups and maybe in PGroups. A VGroup is
  165. started via a GUI object of the BB_VGroup type and ends via a
  166. BB_VGroup_End. VGroups can be compiled in PGroups. A module GUI must have
  167. at least one VGroup. VGroups and PGroups may NOT(!) be placed in groups
  168. of the same type.
  169.  
  170. The GUI objects (BB_Object) are a single-chained list and are terminated with
  171. a NULL.
  172. Because right now all GUI objects are of the same size, one can simply
  173. create an array of the type BB_Object and chain the array elements
  174. appropriately (field <next> points to the next object or to NULL if it is
  175. the last).
  176.  
  177. The individual fields of the objects (eg. <set>, <contents>...) have to be
  178. reset by the module with default values prior to sending the message.
  179. If the message is sent back (BLANK) the module can read the really selected
  180. parameters from the GUI objects.
  181.  
  182. A VGroup is a vertical group of Gadgets. The Gadgets are displayed below
  183. each other in the GUI. If a module GUI has several VGroups then the
  184. vertical Groups will be displayed beside one another.
  185.  
  186. A PGroup contains several VGroups. They can be switched with a cycle or
  187. register gadget (depends on how MUI is configured).
  188.  
  189. A GUI could have this structure:
  190. BB_VGroup->BB_Slider->BB_Slider->BB_VGroup_End->BB_VGroup->BB_Check->
  191. BB_Check->BB_VGroup_End
  192.  
  193. This GUI would have 2 columns. There would be 2 sliders In the left column
  194. and 2 checkmarks in the right. You can find more examples in the supplied
  195. module sourcecodes.
  196.  
  197.  
  198. 4. Description of the GUI objects
  199. ---------------------------------
  200.  
  201. You can attach or insert an underscore "_" to the lables of the
  202. GUI-objects. The following letter will then be the one to be used for the
  203. selection via keyboard. The letters A, C, I, P, S, T can not be used since
  204. they are needed for the lower row of buttons.
  205.  
  206. What follows is the description of the possible GUI objects. Names in <>
  207. are constants or fields within BB_Object.
  208.  
  209. Pagegroup:
  210. Started via <BB_PGroup> and ends via <BB_PGroup_End>.
  211. The default page number is in <set>, <label> points to the NULL terminated
  212. stringarray with the pages's headlines.
  213.  
  214. Verticalgroup:
  215. Started via <BB_VGroup> and ends via <BB_VGroup_End>.
  216. If <label> does not equal NULL it has to point to a string. In this case
  217. the VGroup has a headline and a frame.
  218.  
  219. Checkmark-Gadget:
  220. Recognized by <BB_Check>.
  221. <set> describes the status and <label> points to the label text
  222.  
  223. Stringgadget:
  224. Recognized by <BB_String>
  225. <max> is the maximum number of characters allowed for the stringgadget,
  226. <contents> points to a associated string buffer that has to be allocated BY
  227. THE MODULE, <label> points to the label text.
  228.  
  229. Filegadget:
  230. Recognized by <BB_File>.
  231. <max> is the maximum number of characters allowed for the stringgadget,
  232. <contents> points to a associated string buffer that has to be allocated BY
  233. THE MODULE, <label> points to the label text. Beside the stringgadget,
  234. there is a popbutton for the filerequester.
  235.  
  236. Directorygadget:
  237. Recognized by <BB_Dir>.
  238. This is the same, as BB_File, but it only allows selection of directories.
  239.  
  240. Fontgadget:
  241. Recognized by <BB_Font>.
  242. <max> is the maximum number of characters allowed for the stringgadget,
  243. <contents> points to a associated string buffer that has to be allocated BY
  244. THE MODULE, <label> points to the label text. Beside the stringgadget,
  245. there is a popbutton for the fontrequester.
  246.  
  247. Slider:
  248. Recognized by <BB_Slider>
  249. <min> and <max> describe the slider's boundaries, <set> is the default
  250. value, <label> points to the label text.
  251.  
  252. Cyclegadget:
  253. Recognized by <BB_Cycle>.
  254. <set> describes the selected option, <contents> points to the NULL
  255. terminated stringarray containing the options, <label> points to the label
  256. text.
  257.  
  258. Dummyobject:
  259. Recognized by <BB_Dummy>.
  260. This object is the sole used object if the module doesn't offer any
  261. preferences through GUI onjects.
  262.  
  263.  
  264. 5. Communication with BlitzBlank/BlitzBlankPrefs
  265. -----------------------------------------------
  266.  
  267. When the module is started it gets a pointer to the BlitzBlank Screeninfo
  268. structure. Here the module can set diffs for the screen parameters. For
  269. instance a module could set <width> to 100. This way it would get a screen
  270. 100 pixels wider than the screen the user selected. The module can preset
  271. the <xpos>, <ypos>, <width> and <height> values in the Screeninfo
  272. structure. These values are added to the values selected by the user.
  273. NORMALLY a module won't have to write anything in this structure unless
  274. for instance it wants to have a screen from BlitzBlank but wants to set the
  275. depth on its own (BBF_Color would then be unset). In this case the module
  276. would write the depth to screeninfo->depth BEFORE calling
  277. BBL_SendMessage(). The module can set a minimum depth and/or maximum
  278. depth in <mindepth> and/or <maxdepth>, if it wants to. BlitzBlank
  279. and BPrefs's screenmode-requester will use these boundaries then.
  280.  
  281. The module then sends a Message via BBL_SendMessage() to BlitzBlank/BBPrefs,
  282. after it set the flags in <flags>, the infotext in <infotext> and (if
  283. keyword!=INFO) the pointer to the very first GUI object in <first>.
  284. The GUI objects have to be set with the default parameters. After the
  285. function returns the fields <modpri> and <path> are set. <modpri> is the
  286. selected module taskpriority (will later be used in blank()) and <path> is
  287. the path where the modules can be found. If a module wants to load own data
  288. it will find the data there too (Name convention for extra module data
  289. "BB.Modulename.*"). Also the Screeninfo structure will be set and a screen
  290. has been assigned for the module (only if it requested one) after
  291. BBL_SendMessage(). The GUI objects are then set with the values the user
  292. selected and can be read.
  293.  
  294. The following will then happen entierly in blank():
  295. The module should then make all its precalculations, load neccessary data,
  296. allocate memory, etc. Then it puts its own screen with ScreenToFront
  297. (screeninfo->bbscreen) to front, checks if a CTRL-C arrived in the meantime
  298. and then calls BBL_ModuleRunning().
  299. Then the main routine of the module can be started. Now the selected
  300. parameters are read from the GUI objects. The module must be able to react
  301. to a CTRL-C break signal. In this case the module frees all used resources
  302. (except the screen if it wasn't its own) and calls BBL_ModuleDone(). Now
  303. the module has ended. If the module didn't get a screen from BlitzBlank
  304. although it requested one (screeninfo->bbscreen==NULL) or it couldn't set
  305. its variables due to insufficent memory the module should call
  306. BBL_ModuleDone() at once and shut down afterwards.
  307.  
  308.  
  309. 6. Description of the flags
  310. ---------------------------
  311.  
  312. BBF_Screenmode    : The module supports screenmode selection
  313. BBF_Colors        : The module supports depth selection
  314. BBF_Sample        : Not yet implemented
  315. BBF_NoWatch       : The module doesn't use any(!) CPU time
  316. BBF_NoScreen      : The module doesn't want a screen from BlitzBlank
  317. BBF_FirstScreen   : The module wants the data of the frontmost screen
  318. BBF_CloneScreen   : The module wants a copy of the frontmost screen
  319. BBF_AmigaOnly     : The module is not compatible with graphic cards
  320. BBF_NoMouseBlank  : The module doesn't want the mouse to be blanked
  321. BBF_NoKeyPass     : The module doesn't use a screen and doesn't use a window
  322. BBF_BigWindow     : The blankwindow fills the whole screen
  323. BBF_Interleaved   : BlitzBlank TRIES to give you a screen with an Interleaved BitMap
  324.  
  325. If a module wants its own screen (like BB.Pyro) it will set the BBF_Screenmode
  326. and BBF_Colors flags.
  327.  
  328. If the module directly manipulates the frontmost screen (like BB.Fade) it
  329. will set the BBF_FirstScreen flag. You should be VERY careful with this
  330. kind of modules.
  331.  
  332. If the module manipulates an exact copy of the frontmost screen (like BB.Melt)
  333. it will set the BBF_CloneScreen flag.
  334.  
  335. If BBF_NoMouseBlank isn't set BlitzBlank opens a window on the
  336. associated screen, puts a blank mouse pointer in it (SetPointer()) and
  337. activates it.
  338.  
  339. Advice:
  340. -------
  341.  
  342. If a module wants to open and administer its screen on its own
  343. (BBF_NoScreen) it should use the BBL_BlankMouse() and BBL_UnBlankMouse()
  344. functions to blank the mouse on its screen. 
  345.  
  346. To close its screen it should use BBL_CloseScreenSafe().
  347.  
  348. The screen should be opened with the "SA_Behind,TRUE" tag and should be
  349. brought forward just before BBL_ModuleRunning() with ScreenToFront().
  350.  
  351. Additionally is should set the borders of its screen to black with
  352. VideoControlTags(screen->ViewPort.ColorMap,VTAG_BORDERBLANK_SET,-1,TAG_DONE);.
  353.  
  354. The module MUST write it's self-opened screen into screeninfo->bbscreen!
  355.  
  356. Modules that work with a copy of the frontmost screen (BBF_CloneScreen) can
  357. use a screen with a higher depth than the original screen if they set
  358. screeninfo->depth to the difference.
  359.  
  360.  
  361. 7. Description of the BlitzBlank structures and flags
  362. -----------------------------------------------------
  363.  
  364. #ifndef BLITZBLANK_H
  365. #define BLITZBLANK_H
  366.  
  367. #include <exec/ports.h>
  368. #include <exec/tasks.h>
  369.  
  370.  
  371. /****************************************/
  372. /* $VER: BlitzBlank.h 2.50 (01.03.95)   */
  373. /****************************************/
  374.  
  375. /********************************/
  376. /* Stuff for blitzblank.library */
  377. /********************************/
  378.  
  379. #define BLITZBLANKLIB_VER 6
  380.  
  381. extern struct BitMap   *BBL_AllocBitMap        (ULONG width,ULONG height,ULONG depth,ULONG flags);
  382. extern struct BitMap   *BBL_AllocDBufBitMap    (struct Screen *screen);
  383. extern struct RastPort *BBL_AllocRastPort      (ULONG width,ULONG height,ULONG depth,ULONG flags);
  384. extern void             BBL_BlankDone          (void);
  385. extern struct Window   *BBL_BlankMouse         (struct Screen *screen,UBYTE mode);
  386. extern void             BBL_CloseScreenSafe    (struct Screen *screen);
  387. extern BOOL             BBL_CopyOriginalColors (struct Screen *screen);
  388. extern BOOL             BBL_CopyOriginalScreen (struct Screen *screen);
  389. extern void             BBL_EndDBuf            (ULONG handle);
  390. extern BOOL             BBL_FadeDown           (struct Screen *screen,UBYTE final,UBYTE delay);
  391. extern void             BBL_FreeBitMap         (struct BitMap *bitmap);
  392. extern void             BBL_FreeRastPort       (struct RastPort *rastport);
  393. extern long             BBL_GetDarkestPen      (struct Screen *screen);
  394. extern char*            BBL_GetString          (UWORD num,char *text);
  395. extern ULONG            BBL_InitDBuf           (struct Screen *screen,struct BitMap *bitmap);
  396. extern void             BBL_ModuleRunning      (void);
  397. extern BOOL             BBL_ScreenAvailable    (struct Screen *screen);
  398. extern BOOL             BBL_SendMessage        (struct BB_Message *bbmessage,char *portname);
  399. extern void             BBL_ShowBitMap         (struct Screen *screen,struct BitMap *bitmap,ULONG handle);
  400. extern void             BBL_UnBlankMouse       (struct Window *window);
  401.  
  402.  
  403. /*******************************************************************/
  404. /* The different kinds of GUI-objects for a module's config-window */
  405. /*******************************************************************/
  406.  
  407. #define BB_PGroup     1 /* Indicates the start of a new page group */
  408. #define BB_PGroup_End 2 /* Indicates the end of the page group */
  409. #define BB_VGroup     3 /* Indicates the start of a new vertical group */
  410. #define BB_VGroup_End 4 /* Indicates the end of the vertical group */
  411. #define BB_Check      5 /* Checkmark, uses set field in BB_Object */
  412. #define BB_String     6 /* Textgadget, uses max/contents fields in BB_Object */
  413. #define BB_File       7 /* Stringgadget with attached filerequester */
  414. #define BB_Slider     8 /* Slidergadget, uses min/max/set fields in BB_Object */
  415. #define BB_Cycle      9 /* Cyclegadget, uses set/contents in BB_Object */
  416. #define BB_Dummy     10 /* Dummy, if you want no gadgets at all */
  417. #define BB_Font      11 /* Stringgadget with attached fontrequester */
  418. #define BB_Dir       12 /* Stringgadget with attached filerequester, Dirs only */
  419.  
  420. /*****************************************/
  421. /* Flags used in BB_Message's flag-field */
  422. /*****************************************/
  423.  
  424. #define BBF_Screenmode   (1L <<  0)  /* Allows screenmode-selection */
  425. #define BBF_Colors       (1L <<  1)  /* Allows screendepth-selection */
  426. #define BBF_Sample       (1L <<  2)  /* Not supported yet */
  427. #define BBF_NoWatch      (1L <<  3)  /* Eats no CPU-time, so needs no checking */
  428. #define BBF_NoScreen     (1L <<  4)  /* Wants no screen from BlitzBlank */
  429. #define BBF_FirstScreen  (1L <<  5)  /* Wants pointer to screen in front, be CAREFUL with this! */
  430. #define BBF_CloneScreen  (1L <<  6)  /* Wants a clone from the FrontScreen */
  431. #define BBF_AmigaOnly    (1L <<  7)  /* Not supported yet */
  432. #define BBF_NoMouseBlank (1L <<  8)  /* No mouseblanking from BlitzBlank wanted */
  433. #define BBF_NoKeyPass    (1L <<  9)  /* No keypassing necessary (no mouseblanking, no own active window */
  434. #define BBF_BigWindow    (1L << 10)  /* The blankwindow fills the whole screen */
  435. #define BBF_Interleaved  (1L << 11)  /* BlitzBlank TRIES to give you a screen with an Interleaved BitMap */
  436.  
  437.  
  438. /*****************************************/
  439. /* The structure, that holds config-data */
  440. /*****************************************/
  441.  
  442. struct BB_Object
  443. {
  444.   struct BB_Object* next;     /* Pointer to next object or NULL if last object */
  445.   WORD              type;     /* What kind of GUI-object this is */
  446.   long              min;      /* Minimum value for BB_Slider */
  447.   long              max;      /* Maximum value for BB_Slider, max length of BB_String */
  448.   long              set;      /* Value of BB_Slider, state of BB_Checkmark, BB_Cycle */
  449.   char             *contents; /* Pointer to buffer for BB_String, pointer to stringarray for BB_Cycle */
  450.   char             *label;    /* Label for ALL objects */
  451. };
  452.  
  453.  
  454. /*****************************************************/
  455. /* The message to send to BlitzBlank/BlitzBlankPrefs */
  456. /*****************************************************/
  457.  
  458. struct BB_Message
  459. {
  460.   struct Message    msg;        /* Normal Exec-Message-structure */
  461.   long              flags;      /* Flags for this module */
  462.   char             *infotext;   /* Pointer to infotext for this module */
  463.   struct BB_Object *first;      /* Pointer to first BB_Object or NULL for Info-action */
  464.   WORD              modpri;     /* not of use, if you use the library */
  465.   char             *path;       /* Path to directory for module-data */
  466.   struct Task      *blitzblank; /* not of use, if you use the library */
  467. };
  468.  
  469.  
  470. /***************************************/
  471. /* The BlitzBlank-Screeninfo-structure */
  472. /***************************************/
  473.  
  474. struct BB_Screeninfo
  475. {
  476.   WORD             xpos;       /* should be 0 */
  477.   WORD             ypos;       /* should be 0 */
  478.   WORD             width;      /* User-selected screen-width */
  479.   WORD             height;     /* User-selected screen-height */
  480.   WORD             depth;      /* User-selected screen-depth */
  481.   long             mode;       /* User-selected screen-mode */
  482.   struct Screen   *bbscreen;   /* module screen */
  483.   struct Window   *bbwindow;   /* blank window */
  484.   WORD             mindepth;   /* desired minimum depth or 0 */
  485.   WORD             maxdepth;   /* desired maximum depth or 0 */
  486. };
  487.  
  488.  
  489. /************************************************************/
  490. /* Flag-definition for BBL_AllocBitMap()/BBL_AllocRastPort, */
  491. /* if you don't have the V39-includes                       */
  492. /************************************************************/
  493.  
  494. #ifndef BMB_CLEAR
  495. #define BMB_CLEAR 0
  496. #define BMB_DISPLAYABLE 1
  497. #define BMB_INTERLEAVED 2
  498. #define BMF_CLEAR (1l<<BMB_CLEAR)
  499. #define BMF_DISPLAYABLE (1l<<BMB_DISPLAYABLE)
  500. #define BMF_INTERLEAVED (1l<<BMB_INTERLEAVED)
  501. #endif
  502.  
  503. #endif
  504.  
  505.  
  506. 8. Description of the global definitions of a module (example)
  507. --------------------------------------------------------------
  508.  
  509. /* Inclusion of the BlitzBlank definitions */
  510.  
  511. #include <pragmas/blitzblank_pragmas.h>
  512. #include <BlitzBlank.h>
  513.  
  514. /* Definition of the BlitzBlankBase */
  515.  
  516. struct Library *BlitzBlankBase;
  517.  
  518. /* Versionstring */
  519.  
  520. static const char version[]="$VER: BB.Melt 2.50 (26.12.94)";
  521.  
  522. /* Definition of the texts (in english) */
  523.  
  524. char *text[]={"\33c\33uMelt\33n\n\nModule for BlitzBlank\n\nCopyright1994\nby\nThomas Börkel",
  525.               "_Speed:",
  526.               "S_ize:"};
  527.  
  528. /* Definition of the GUI objects with the default parameters */
  529.  
  530. struct BB_Object object[]={ {&object[1],BB_VGroup    ,0,  0,  0,NULL,NULL},
  531.                             {&object[2],BB_Slider    ,1,150,100,NULL,NULL},
  532.                             {&object[3],BB_Slider    ,1,100, 30,NULL,NULL},
  533.                             {NULL      ,BB_VGroup_End,0,  0,  0,NULL,NULL} };
  534.  
  535.  
  536. /* Definition of the BB_Message */
  537.  
  538. struct BB_Message message;
  539.  
  540. /* Definition of the pointer to BB_Screeninfo */
  541.  
  542. struct BB_Screeninfo *screeninfo;
  543.  
  544.  
  545. 9. Exact definition of the main program (example)
  546. -------------------------------------------------
  547.  
  548. The main program should look like this (example in C):
  549.  
  550. void main (int argc,char **argv)
  551. {
  552.   int i;
  553.  
  554. /* Open the blitzblank.library */
  555.  
  556.   if (!(BlitzBlankBase=OpenLibrary ("blitzblank.library",BLITZBLANKLIB_VER)))
  557.     exit (0);
  558.  
  559. /* Set the flags */
  560.  
  561.   message.flags=BBF_CloneScreen;
  562.   message.first=&object[0];
  563.  
  564. /* BLANK/CONFIG/INFO? */
  565.  
  566.   if (strcmp (argv[1],"BLANK")==0)
  567.   {
  568.  
  569. /* get screeninfo */
  570.  
  571.     StrToLong (argv[3],(long *) &screeninfo);
  572.  
  573. /* Set message and GUI objects */
  574.  
  575.     BBL_SendMessage (&message,argv[2]);
  576.  
  577. /* Screen open? */
  578.  
  579.     if (screeninfo->bbscreen)
  580.  
  581. /* Blank */
  582.  
  583.       blank ();
  584.  
  585. /* Stop blank routine */
  586.  
  587.     BBL_BlankDone ();
  588.   }
  589.   else
  590.   {
  591.  
  592. /* Get locale texts (200=number you get from the BB-Author) */
  593.  
  594.     message.infotext=BBL_GetString (200,text[0]);
  595.  
  596.     for (i=1;i<=5;i++)
  597.       object[i].label=BBL_GetString (200+i,text[i]);
  598.  
  599.     if (strcmp (argv[1],"CONFIG")==0)
  600.     {
  601.       BBL_SendMessage (&message,argv[2]);
  602.     }
  603.     else
  604.     {
  605.       message.first=NULL;
  606.       BBL_SendMessage (&message,argv[2]);
  607.     }
  608.   }
  609.  
  610. /* Close library */
  611.  
  612.   CloseLibrary (BlitzBlankBase);
  613.   exit (0);
  614. }
  615.  
  616.  
  617. 10. Exact description of blank()
  618. --------------------------------
  619.  
  620. void blank (void)
  621. {
  622.  
  623. /* Make all preparetions (allocate memory etc.) */
  624.  
  625. /* if you've opened the screen yourself, put it in screeninfo->bbscreen */
  626.  
  627.   if (!CheckSignal (SIGBREAKF_CTRL_C))
  628.   {
  629.  
  630. /* Get the screen to front */
  631.  
  632.      ScreenToFront (screeninfo->bbscreen);
  633.  
  634.      BBL_ModuleRunning (); /* your screen must be already in front here */
  635.  
  636. /* Main program with break possibility via SIGBREAKF_CTRL_C */
  637. /* Read selected parameters from the GUI objects            */
  638.  
  639.   }
  640.  
  641. /* Clean up */
  642.  
  643.   return;
  644. }
  645.  
  646.  
  647. 11. Advice for supporting the locale.library
  648. --------------------------------------------
  649.  
  650. BlitzBlank/BlitzBlankPrefs use ONE catalog "blitzblank.catalog". Within are
  651. all localized strings for BlitzBlank, BlitzBlankPrefs and all modules.
  652. Which strings correspond to which program is determined by the BlitzBlank
  653. author. The module programmers should incorporate the english text into
  654. their module and submit a corresponding german text to the author. He will
  655. then put the texts into the catalog.
  656. Until now these numbers are used for texts:
  657.  
  658. 001-199: BlitzBlank/BlitzBlankPrefs
  659. 200-209: BB.Melt
  660. 210-219: BB.Fade
  661. 220-229: BB.Pyro
  662. 230-239: BB.Crumble
  663. 240-249: BB.Mosaic
  664. 250-259: BB.Aquarium
  665. 260-269: BB.Flash
  666. 270-279: BB.Lines
  667. 280-289: BB.Butterfly
  668. 290-299: BB.Slideshow
  669. 300-309: BB.Starfield
  670. 310-319: BB.Splines
  671. 320-329: BB.AmigaSign
  672. 330-339: BB.PatternCycling
  673. 340-349: BB.Execute
  674. 350-359: BB.Worms
  675. 360-379: BB.Tiles
  676. 380-399: BB.Clock
  677. 400-409: BB.Mandel
  678. 410-419: BB.Electric
  679. 420-429: BB.Fountain
  680. 430-439: BB.Guru
  681. 440-449: BB.Noise
  682. 450-459: BB.Radar
  683. 460-469: BB.Snow
  684. 470-479: BB.Worms2
  685. 480-499: BB.Spot
  686. 500-509: BB.Life
  687. 510-519: BB.Dissolve
  688. 520-539: BB.Tunnel
  689. 540-549: BB.Gravity
  690. 550-559: BB.Skyline
  691. 560-589: BB.Text
  692. 590-599: BB.FlyingToaster
  693. 600-629: BB.Plasma
  694. 630-639: BB.TicTacToe
  695. 640-649: BB.Maze
  696. 650-659: BB.ARose
  697. 660-669: BB.Fractal
  698. 670-699: Reserved
  699. 700-709: BB.Goats
  700. 710-729: BB.ASwarm
  701.  
  702.  
  703. 12. AmigaGuide documentation for the modules
  704. --------------------------------------------
  705.  
  706. The documentation for the modules will be incorporated into the global
  707. AmigaGuide document BlitzBlank.Guide and will be displayed by
  708. BlitzBlankPrefs if the HELP-key is pressed inside the modules prefs window.
  709. The module's documentation with copyright and address of the author should
  710. be submitted to the BlitzBlank author in english and german (if possible)
  711. so they can be build into the guide.
  712.  
  713.  
  714. 13. Tips & tricks
  715. -----------------
  716.  
  717. - If BlitzBlank is started from a shell all CON output of the modules are
  718.   displayed in this shell (very good for debugging). If BlitzBlank is
  719.   started from the WB and the module attempts CON output Enforcer hits will
  720.   occur. This is normal because the modules don't get an output channel if
  721.   they are started from WB. CON output may only be used for debugging
  722.   purposes.
  723.  
  724. - The ARexx DEBUG instruction makes it possible to start a module that then
  725.   can only be stopped through the ARexx UNBLANK instruction. This gives the
  726.   oppurtunity to test the module without watching what the mouse is doing
  727.   all the time.
  728.  
  729. - The best way to understand how to program a module is to look at the
  730.   supplied source codes.
  731.  
  732. - The name convention for additional data is: "BB.Modulename.xyz"
  733.  
  734. - Not only the neccessary functions are in the blitzblank.library but also
  735.   some very useful ones (eg for double-buffering!).
  736.  
  737. - If a module should use the randomizer one shouldn't forget to set the
  738.   seed (for instance with the current time, look at BB.Lines for an
  739.   example).
  740. - Normally, you will draw into &screeninfo->bbscreen->RastPort, which is
  741.   pretty fast. But with this, you get no clipping. To have clipping,
  742.   set the flag BBF_BigWindow and draw into screeninfo->bbwindow->RPort.
  743.