home *** CD-ROM | disk | FTP | other *** search
/ Millennium Time Capsule / AC2000.BIN / disks / ac12disk / joe_eng.142 / manual / ascii / coder.txt < prev    next >
Text File  |  1998-07-30  |  7KB  |  198 lines
  1. Programmer's guide
  2.  
  3. 1) Foreword
  4.  
  5. Since 1.40 version, you can add modules to Joe. These can be tags generators
  6. or others which will facilitate HTML coding and Web editing.
  7.  
  8. You can, without my authorisation, program your own module.
  9. You can make Everyware : Public domain (with source code), Freeware (I would
  10. appreciate). You can distribute also your module as shareware or commercial
  11. program.
  12. If you want an example
  13. of source code for a module, just snail- or e-mail me. I will send you freely
  14. GFA code of some modules in LST format.
  15. But there are restrictions upon this source code :
  16. - do not spread this code without my authorisation.
  17. - do not distribute your module as expensive shareware (>70 Francs, 10 euros)
  18. or commercial program if created basicaly on my source code. Contact me if
  19. you you think your work on my source code is worth an expensive shareware or
  20. a commercial software.
  21.  
  22. The sending of my source code is a moral agreement.
  23.  
  24. The following is recommendations, you don't have to subscribe at these words,
  25. but I would appreciate if you do. Your module-program should :
  26.  
  27. be compatible with all the AtariOS (MagiC, MiNT, TOS...) and respect porperly
  28. AES and VDI. run in only one window (as small as possible, "windows-like"
  29. with several form-dials in the same window), with a minimum of blocking
  30. extern form-dials, and the menu (if present) be included in the window.
  31. run without Joe, ie with another HTML designer program or freely.
  32.  
  33.  
  34. 2) Be called by Joe
  35.  
  36. If you want your module-program to be launched under Joe application, it
  37. MUST :
  38. - have the *.PRG filename extension
  39. - be in directory declared in the options of Joe
  40. have a text file besides the *.PRG file. This texte file has the same
  41. filename of the module and has the *.JXM extension.
  42. - The text must contain :
  43. in the first line : a text (30 caracters) which will be integrated in the
  44. modules launching pop-up.
  45. in the second line : a number (WORD, INT). Only the first bit is used now, but the
  46. others bits may be used in the future with next versions of Joe.
  47. Bit 0 at 1 : ability to be called in the pop-up.if at 0 : the module doesn't
  48. appear in the pop-up.
  49.  
  50.  
  51. 3) Exchange protocol
  52.  
  53. a. The command line
  54.  
  55. Parameter given when launching a module is a Pascal string (1 byte describing
  56. the lenght of the line, the data-caracters, and the null-byte terminator).
  57. Data are structured like this :
  58.  
  59. 8 caracters corresponding to the application wihch has called the module.
  60. This 8 caracters will be given with no transformation to APPL_FIND function.
  61. If Joe is the caller, then the 8 caracters are : "JOE     "
  62. The next caracters (to the ending null-byte) describe a filename the HTML
  63. file the caller is editing.
  64.  
  65. The module should get the first 8 caracters of the command line, and
  66. APPL_FIND. If there's an error or the caller doesn't exist, the module should
  67. not take the rest of the line or consider the command line does not applies
  68. to Joe exchange protocol.
  69.  
  70. b. Monotasking mode
  71.  
  72. The module, before quitting, saves the tag or whatever data for the caller,
  73. in the clipboard. Joe accepts *.HTM (text with all lines terminates by LF+CR)
  74. and *.STG (C string format, considered as a macro, so you can use "|" and
  75. "~") files. Therefore SCRAP.HTM or SCRAP.STG .
  76. When quitting, the module returns a value (QUIT ret&) :
  77. If 0 : the caller loads nothing
  78. If 1 : the caller loads SCRAP.HTM
  79. If 2 : the caller loads SCRAP.STG
  80. If esle : no yet supported
  81.  
  82. You can return for others callers than Joe others values. Please, tell me
  83. about what values you have added to normalize this.
  84.  
  85. c. Multitasking mode
  86.  
  87. NB : this applies also for accessories in monotasling mode.
  88.  
  89. Joe supports VA_START message and Drag and Drop protocol.
  90.  
  91. The exchanges with modules use the GEM pipe ("Tube GEM" in French). The
  92. following decribes the calls. X_adr% is a 16 bytes buffer, mem% is a buffer
  93. located in the global memory (X_mem%=GEMDOS(68,L:len%,W:32)) if possible
  94. (else: GEMDOS(72,...). 16 bytes buffers are managed by EVNT_MULTI.
  95.  
  96. * SEND TEXT TO THE CALLER
  97.  
  98. caller_id&=APPL_FIND("????????")
  99. ' "????????" is the 8 caracter string read in the command line.
  100. IF caller_id&>0
  101.   INT{module_adr%}=20140
  102.   INT{module_adr%+2}=module_id&
  103.   INT{module_adr%+4}=0
  104.   INT{module_adr%+6}=0
  105.   INT{module_adr%+8}=0
  106.   INT{module_adr%+10}=format&
  107.   ' (1=*.HTM or *.TXT, 2=*.STG, 0 or else=Joe reads nothing)
  108.   LONG{module_adr%+12}=module_mem%
  109.   ' (address in the global memory where the module has put the text)
  110.   ~APPL_WRITE(caller_id&,16,module_adr%)
  111. ENDIF
  112.  
  113. When reading this in his 16 bytes buffers, the caller wil or will not read
  114. the memory, and respond to the module with :
  115.  
  116. * CALLER RESPOND TO MODULE, TEXT RETRIEVED
  117.  
  118. module_id&=INT{caller_adr%+6}
  119. INT{caller_adr%}=20141
  120. INT{caller_adr%+2}=caller_id&
  121. INT{caller_adr%+4}=0
  122. INT{caller_adr%+6}=0
  123. INT{caller_adr%+8}=0
  124. INT{caller_adr%+10}=0
  125. INT{caller_adr%+12}=0
  126. INT{caller_adr%+14}=0
  127. ~APPL_WRITE(module_id&,16,caller_adr%)
  128.  
  129. To facilite the manipulation of the entire file edited by the caller, the
  130. module can ask to the caller an automatic save of the text :
  131.  
  132. * REQUEST AUTOMATIC SAVE TO CALLER
  133.  
  134. caller_id&=APPL_FIND("????????")
  135. ' "????????" is the 8 caracter string read in the command line.
  136. IF caller_id&>0
  137.   INT{module_adr%}=20142
  138.   INT{module_adr%+2}=module_id&
  139.   INT{module_adr%+4}=0
  140.   INT{module_adr%+6}=0
  141.   INT{module_adr%+8}=0
  142.   INT{module_adr%+10}=0
  143.   INT{module_adr%+12}=0
  144.   INT{module_adr%+14}=0
  145.   ~APPL_WRITE(caller_id&,16,module_adr%)
  146. ENDIF
  147.  
  148. The caller will save its data and tell next the module it's done, give the
  149. address buffer of filename, and the handle of the window if not iconified and
  150. existing :
  151.  
  152. * CALLER RESPOND TO MODULE, (OWN DATA SAVED) AND INFORMATION
  153.  
  154. module_id&=INT{caller_adr%+6}
  155. INT{caller_adr%}=20144
  156. INT{caller_adr%+2}=caller_id&
  157. INT{caller_adr%+4}=0
  158. INT{caller_adr%+6}=window_handle_of_caller&
  159. INT{caller_adr%+8}=0
  160. INT{caller_adr%+10}=0
  161. LONG{caller_adr%+12}=caller_mem%
  162. ' the caller has put the filename in a 256 bytes buffer, in global memory.
  163. ' The filename buffer is permanent, so the module has no need to respond
  164. ' to the caller. But the module must ask the caller the address
  165. ' filename : the caller may quit, clean his memory and not respond.
  166. ~APPL_WRITE(module_id&,16,caller_adr%)
  167.  
  168. Be carefull with the widow handle : it's given to close, or shadow, the
  169. caller window to avoid caller data manipulation during module computing. DO
  170. NOT WIND_SET or whatever else the caller window directly, use GEM pipe and
  171. fill the 16 bytes buffer as the Screen manager do.
  172. You can freeze and unfreeze the caller if you know how to do it (See MagiC
  173. developpers documention).
  174.  
  175. In some cases, you don't need the caller data to be saved. You just only want
  176. informations, so :
  177.  
  178. * REQUEST INORMATION TO CALLER
  179.  
  180. caller_id&=APPL_FIND("????????")
  181. ' "????????" is the 8 caracter string read in the command line.
  182. IF caller_id&>0
  183.   INT{module_adr%}=20143
  184.   INT{module_adr%+2}=module_id&
  185.   INT{module_adr%+4}=0
  186.   INT{module_adr%+6}=0
  187.   INT{module_adr%+8}=0
  188.   INT{module_adr%+10}=0
  189.   INT{module_adr%+12}=0
  190.   INT{module_adr%+14}=0
  191.   ~APPL_WRITE(caller_id&,16,module_adr%)
  192. ENDIF
  193.  
  194. The caller will respond to the module with the same message if there was an
  195. automatic save. Therefore with the 20144 code, the window handle, and the
  196. data filename in the caller buffer.
  197.  
  198.