home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / commod / sdark14s.lha / docs / programmers.doc next >
Text File  |  1993-03-21  |  14KB  |  401 lines
  1. @AUTHOR   "Thomas Landspurg"
  2.  
  3. ## $VER: SuperDark.guide v1.1 (12.2.93)
  4.  
  5. ----------------------------------------------------------------------------------
  6. Main "SuperDark prog"
  7. ----------------------------------------------------------------------------------
  8.  
  9.     Writing your own modules for superdark:
  10.  
  11.     'Overview'
  12.     'Info'
  13.     'Dark function'
  14.     'MyGadg'
  15.     'The info text'
  16.     'Problems'
  17.  
  18. ----------------------------------------------------------------------------------
  19. Overview "Overview"
  20. ----------------------------------------------------------------------------------
  21. @Toc    "Main"
  22. I Overview:
  23.  
  24.     How to add modules to SuperDark.
  25.  
  26. - It is not very difficult to add your own module to Superdark, but
  27. you have to read carefuly this doc, because there is some important 
  28. things to understand!
  29.  
  30. You have to do   four things to add a new module in SuperDark:
  31.  
  32. * Create your own 'dark()' procedure, that's the procedure called at
  33.   screen blanking. That's the biggest part of the job.
  34. * Add the 'proc_init()','proc_save()','proc_end()' function. Usually, these
  35.   function are empty. But for special purpose, you could fill them, look
  36.   at the doc.
  37. * Add a 'my_gadg[]' array. This array is used to create the param window,
  38.   but also to read and save parameters. Bery powerful, and easy to use
  39.   after ypu've read the doc!
  40. * Create an 'info' text. This should be easy,no?
  41.  
  42. Notes:
  43.     * YOU MUST link your module with the proc_main.o object. Proc_main
  44. will make some important initialisation, contain important function for
  45. you!
  46.     * I use some special keyword of the Lattice compile, like _saveds.
  47. If you don't have them, check your compiler's documentation.
  48.  
  49. The simplest way to add a new module is to take a look at the module named
  50. "rien.dark.c", this module does aboslutly nothing, but you can use it
  51. at a skeletton program.
  52.  
  53. ----------------------------------------------------------------------------------
  54. Info "Info"
  55. ----------------------------------------------------------------------------------
  56.  
  57. II What is a module for SuperDark ?
  58.  
  59. - It's an executable program, loaded by SuperDark.
  60. - You have link it with proc_main.o.
  61. - Proc_main.o will make initialisation and wait for a signal from
  62.   superdark, and then will call your 'dark' function.
  63.  
  64. ----------------------------------------------------------------------------------
  65. dark "Dark function"
  66. ----------------------------------------------------------------------------------
  67. III
  68.     The dark() function:
  69.  
  70. This function is called by proc_main when the screen should be blanked.
  71. You can ask for a copy of the frontmost screen. To do this, look at the
  72. 'proc_init()' function.
  73. So you can put what you want here, but remeber these limitations:
  74.  
  75. - Don't use any printf in your program
  76. - Don't make any global auto-initalised variable. This may be cause some
  77.   problems if you don't see exactly what happens. Because when your dark()
  78.   function is called two time, the global are not reset to her initial value.
  79.   So if you use global var and change their value, be careful.
  80. - Try to don't use the whole CPU time. Use WaitTOF(), Delay(), Wait()... But
  81.   you are a good programmer, so you know what to do!
  82.  
  83.  To test if your function have to exit, you have the tst_end() function.
  84. This function will return TRUE if you have to exit, or FALSE if you have to
  85. continue. 
  86.     Example:
  87.         while(tst_end()==FALSE){
  88.             do what you want...
  89.         }
  90.   The other function is wait_end(). This function will only return at the end of the
  91. blanking time.
  92.  
  93. ----------------------------------------------------------------------------------
  94. proc_init() "proc_init()"
  95. ----------------------------------------------------------------------------------
  96. IV proc_init(),proc_save() and proc_end()
  97.  
  98. proc_init() is called after your module have been loaded. You can do
  99. special initialisation here, but don't use to much memory.
  100. That's here that you told if you want a copy of the current frontmost screen
  101. be opened for you. To do this, you have to do this:
  102.  
  103.     p_data_proc->type_screen=SCR_GIVEN;
  104.  
  105. You can alos tell to superdark that your module should only run with
  106. superdark for WB2.0 or higher.
  107.  
  108.     p_data_proc->code_ret=DARK_WB_20;
  109.  
  110. proc_save() is no more used, but is still here for compatibility...
  111.  
  112. proc_end() is called when the module have to be removed from memory. You can
  113. free what you've allocated in proc_init().
  114.  
  115. ----------------------------------------------------------------------------------
  116. MyGadg "MyGadg"
  117. ----------------------------------------------------------------------------------
  118.  
  119. V The my_gadg array....
  120.  
  121. This one of the most powerful of superdark. Each module can have a parameter
  122. window. To do this, you have to define this window, but in a special manner.
  123. This array is an array of type tom_gadget. This is the definition of the
  124. type tom_gadget (from includes/tom_gadget.h) :
  125.  
  126. typedef    struct    tom_gadget{
  127.     char    *GadgetText;        /* Text of the gadget on screen. */                
  128.     type_gadget    type_gadg;    /* The type of the gadget, see later */
  129.     short    int    LeftEdge,TopEdge;/* position            */
  130.     short    int    Width,Height;    /* size                */
  131.     short    int    value;        /* value !            */
  132.     short    int    d1,d2,d3;    /* Used for special purpose.... */
  133.     char    *p_data;        /* Used for special purpose.... */
  134.     struct    Gadget    *p_gadg;    /* Internal use only        */
  135.  
  136. };
  137.  
  138. Note that the four standart gadget "ok","test","cancel","help" are
  139. automaticly added!
  140.  
  141. Let's see these field:
  142.  
  143. char    *GadgetText:
  144.     So it's the text of your gadget in the configuration window, but also
  145. of the corrseponding value in the TOOL TYPE list. Yes, because SuperDark
  146. se these informations to save the configuration as ToolTypes in the .info of
  147. the module.
  148.     You can use shorcut, by using '_'. Example, a gadget named TEST can
  149. have the shortcut T if his name is:
  150.     "_TEST"
  151.  
  152. type_gadget type_gadg:
  153.     Define the type of the gadget. These type are availaible:
  154. (note that they are also availble on WB1.3 for the most of them)
  155.  
  156.     The following type are available(and look at the 'exemple':
  157.  
  158.     'END_LISTE'
  159.     'BUTTON'
  160.     'SLIDER'
  161.     'CHECKBOX'
  162.     'MX'
  163.     'CYCLE'
  164.     'LISTVIEW'
  165.     'OWN_GADGET'
  166.     'STRING'
  167.     'INTEGER'
  168.     'SCREEN'
  169.     'FONT'
  170.     'DATA_STRING'
  171.     'IMAGE'
  172.  
  173. LeftEdge,TopEdge,Width,Height:
  174.     Position and size of the gadget...nothing else to say!
  175. ----------------------------------------------------------------------------------
  176. END_LISTE 
  177. ----------------------------------------------------------------------------------
  178.     END_LISTE:
  179.  
  180.         This is not really a type, but each tom_gadget array should
  181.         end with this value! Remember it!!!
  182. ----------------------------------------------------------------------------------
  183. BUTTON
  184. ----------------------------------------------------------------------------------
  185.     BUTTON:
  186.         A simple button. You can define a function called when the 
  187.         button is pressed, by giving a pointer to this function
  188.         in the p_data field.
  189. ----------------------------------------------------------------------------------
  190. SLIDER
  191. ----------------------------------------------------------------------------------
  192.     SLIDER:
  193.         A normal slider. The direction of the slizer (horiz/vertical)
  194.         is defined by the ratio Width/Height. If Width is > Height,
  195.         this will be an horizontal slider, otherwhise it's an vertical
  196.         one.
  197.  
  198.         * value must contain the initial value of the slider,
  199.  
  200.         * d1 and d2 must contain the range of the slider
  201.  
  202.         * if p_data is not nul, it must contain a pointer to the
  203.         variable wich will receive a copy of the current value
  204.         of the slider.
  205. ----------------------------------------------------------------------------------
  206. CHECKBOX
  207. ----------------------------------------------------------------------------------
  208.  
  209.     CHECKBOX:
  210.         Checkbock gadget.
  211.  
  212.         * value contain the initial value, and will be re-actualised,
  213. ----------------------------------------------------------------------------------
  214. MX
  215. ----------------------------------------------------------------------------------
  216.     MX:
  217.         Multiple choice gadget.
  218.  
  219.         * p_data must contain a pointer to an array of char
  220.             example: p_data={"Choice1","Choice2","Choice3",NULL}
  221.  
  222.         * value contain the initial value, and will be re-actualised,
  223.  
  224. ----------------------------------------------------------------------------------
  225. CYCLE
  226. ----------------------------------------------------------------------------------
  227.     CYCLE:
  228.         Cycle gadget.
  229.         Same kind of configuration than the MX gadget.
  230.  
  231. ----------------------------------------------------------------------------------
  232. LISTVIEW
  233. ----------------------------------------------------------------------------------
  234.     LISTVIEW:
  235.         Listview gadget.
  236.  
  237.         * p_data must containt a pointer to a List structure. the
  238.         name of each node of the list will be be show on screen.
  239.  
  240.         * value contain the position of the initial selected value,
  241.         and will be re-actulised.
  242. ----------------------------------------------------------------------------------
  243. OWN_GADGET
  244. ----------------------------------------------------------------------------------
  245.     OWN_GADGET:
  246.         Very special purpose gadget!!!!
  247.         No time to describe it now...sorry
  248. ----------------------------------------------------------------------------------
  249. STRING
  250. ----------------------------------------------------------------------------------
  251.     STRING:
  252.         String gadget
  253.  
  254.         * p_data must contain a pointer to a buffer of char. This buffer
  255.         will containt the value of the string gadget.
  256.  
  257.         * d1 MUST CONTAINT the size of the buffer.
  258. ----------------------------------------------------------------------------------
  259. INTEGER
  260. ----------------------------------------------------------------------------------
  261.     INTEGER:
  262.         Integer gadgt.
  263.  
  264.         *value contain the initial value, and will be re-actualised,
  265.  
  266.         *d1 contain the max number of digits for the number.
  267. ----------------------------------------------------------------------------------
  268. SCREEN
  269. ----------------------------------------------------------------------------------
  270.     SCREEN:
  271.         High level gadget....
  272.         This gadget will only be active if reqtools.library v38 or
  273.         higher is present on your system.
  274.         It allow you to choose a screen resolution, size, and overscan
  275.         value, by using the screen requester from the reqtools lib.
  276.  
  277.         * value contain the initial Overscan mode of the screen,
  278.         and will be re-actualised. Look at intuition/screens.h
  279.         * d1 contain the initial Width of the screen, and will be
  280.         re-actualised
  281.         * d2 contain the initial Height of the screen, and will be
  282.         re-actualised
  283.         * d2 contain the initial Depth of the screen, and will be
  284.         re-actualised
  285.         * p_data contain the initial Mode ID of the screen, and will be
  286.         re-actualised
  287.         Note:
  288.         If d3 (depth) is null, this mean that none of the value is
  289.         significative.
  290.  
  291. ----------------------------------------------------------------------------------
  292. FONT
  293. ----------------------------------------------------------------------------------
  294.     FONT:
  295.         The second high level gadget....
  296.         This gadget will only be active if reqtools.library  is
  297.         present on your system.
  298.         It allow you to choose a font, include size and attributes.
  299.  
  300.         * p_data is a pointer to a TextAttr structure.
  301.           IMPORTANT NOTE: This text attr must have the field ta_Name
  302.           initialized with a pointer to a string buffer, with enough
  303.           space to put the biggest name of the available font
  304.  
  305.  
  306. ----------------------------------------------------------------------------------
  307. DATA_STRING 
  308. ----------------------------------------------------------------------------------
  309.     DATA_STRING:
  310.         This data type is only used for configuration. I mean than
  311.         you won't see anything on configuration window, but a string
  312.         will be saved and loaded in the configuration file.
  313. ----------------------------------------------------------------------------------
  314. IMAGE
  315. ----------------------------------------------------------------------------------
  316.     IMAGE
  317.         With this data, you can include an image in your parameter
  318.         window. Just put a pointer to an image structure in the 
  319.         p_data field
  320. ----------------------------------------------------------------------------------
  321. EXEMPLE
  322. ----------------------------------------------------------------------------------
  323.  
  324.     Let's we want to make a parameter window, with three things:
  325.     - a checbox,
  326.     - a slider , wich can have value from -10 to 50
  327.     - a "screen" button.
  328.  
  329. struct    tom_gadget    my_gadg[]={
  330.     {"_Check it"    ,CHECKBOX  , 100, 10, 10,10,0,0,0,0,0},
  331.     {"_slide it"    ,SLIDER  ,   100, 25, 10,10,10,-10,50,0,0},
  332.     {"s_creen"      ,SCREEN  ,   200, 10, 50,10,0,0,0,0,0}};
  333.  
  334.     The parameter window will look like this:
  335.  
  336.     -------------------------------------------------
  337.     |                        |
  338.     |           _     ________        |
  339.     |   Check it  | |        |screen|        |
  340.     |           -         --------        |
  341.     |          ___________________        |
  342.     |   slide it  |          #      |        |
  343.     |             -------------------        |
  344.     |                        |
  345.     |        Ok      Test      Cancel      Info    |
  346.     |                        |
  347.     -------------------------------------------------
  348.  
  349. and when you press save, you'll see in the tooltype of your module:
  350.  
  351.     CHECK IT=FALSE
  352.     SLIDE IT=20
  353.     SCREEN  =320 x 256 x 3 ID=21000 OVSCN=0
  354. Nice no?
  355.  
  356.  
  357. ----------------------------------------------------------------------------------
  358. Info_text "Info_text"
  359. ----------------------------------------------------------------------------------
  360.     The information text:
  361.  
  362.     It's the text show when you press the "Info" button. It's just an
  363. ascii string, named p_text_info. Example:
  364.  
  365. char *p_text_info=
  366. "   Hi evrybody\n"
  367. "now I can do my\n"
  368. "own module for\n"
  369. "    SUPERDARK!\n";
  370.  
  371.     Note the \n at the end of each line
  372. ----------------------------------------------------------------------------------
  373. Problems "Problems"
  374. ----------------------------------------------------------------------------------
  375.  
  376. VI If it doesn't work....
  377.  
  378. Hum....take a look at the other sourcecodes in the disk 
  379.  
  380. If this still doesn't work, you can send me you module and I'll try to
  381. make it work....
  382.  
  383. my  adress
  384.  
  385.     Thomas LANDSPURG
  386.     9, Place Alexandre 1er
  387.     78000 VERSAILLES
  388.     FRANCE
  389.  
  390.     FidoNet: 2:320/104.18
  391.     AMyNet:    39:180/1.18
  392.     UseNet:    Thomas_Landpsurg@ramses.gna.org
  393.  
  394.  SuperDark may not be included with any commercial product nor may it be
  395.  sold for profit either separately or as part of a compilation without
  396.  my permission. It may be included in non-profit disk collections such as the
  397.  Fred Fish collection. It may be archived & uploaded to electronic bulletin
  398.  board systems as long as all files remain together & unaltered.
  399.  
  400.  
  401.