home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / utilities / utilsm / megaboard / Docs / ProgGuide < prev    next >
Text File  |  1995-03-30  |  19KB  |  615 lines
  1.                 Guide for writing Special icons for Megaboard
  2.                 ---------------------------------------------
  3. ----------------
  4. - Introduction -
  5. ----------------
  6. This file explains how to create new special icons for Megaboard, it will
  7. only be of interest to programmers, other users should refer to the "Guide"
  8. file for information on general use.
  9. For a step-by-step tutorial on creating a special icon see the ProgTutrl
  10. file.
  11.  
  12. ------------------
  13. - Relevant files -
  14. ------------------
  15. The files within Megaboard's application directory used by special icons are
  16. the script file named "Cstm_Scrpt" and the files contained in the "Special"
  17. subdirectory.
  18.  
  19. ----------------------
  20. - Creating new icons -
  21. ----------------------
  22. Creating a new icon consists of two steps, writing the icon's definition in
  23. the script file and writing a set of ARM code entry points needed to maintain
  24. the icon.
  25.  
  26. Icon definition commands
  27. ------------------------
  28. The script file consists of the following commands (Not case sensitive):
  29. *  Start_Icon
  30. *  Name:
  31. *  Author:
  32. *  Width:
  33. *  Height:
  34. *  Worksize:
  35. *  Update:
  36. *  Mouse_State:
  37. *  KeyPress_State:
  38. *  Message_State:
  39.    Start_Parameters
  40.    <Parameter name>:<default value>
  41.                  ...
  42.    <Parameter name>:<default value>
  43.    End_Parameters
  44. *  End_Icon
  45. The Commands marked with an asterisk are mandatory and must be present in
  46. every icon definition.
  47.  
  48. Writing an icon definition
  49. --------------------------
  50. An Icon definition always begins with the command Start_Icon, which may be
  51. preceded by any number of spaces, but otherwise must be the only item on the
  52. line.
  53. Start_Icon is followed on subsequent lines by a list of commands terminated
  54. by the End_Icon command.
  55.  
  56. Syntax of script commands
  57. -------------------------
  58. All commands except Start_Icon, End_Icon, Start_Parameters and
  59. End_Parameters have the following syntax:
  60. |<Spaces>|<Command>:|<Spaces>|<Value>
  61. Where items contained in || are optional.
  62. Example use:
  63.  
  64.      Width: 100
  65. ^^^^^      ^
  66.   ⇧        ⇧
  67. Leading   Spaces
  68. Spaces   separating
  69.  are      command
  70. ignored     and
  71.            value
  72.             are
  73.            also
  74.           ignored
  75. The command above sets the special icon's width to 100 OS units.
  76. The following commands, however, have the same effect:
  77. Width:100
  78. Width:                                                100
  79.                                              Width:100
  80.  
  81.  
  82. Command descriptions
  83. --------------------
  84. Now for a detailed description of script commands:
  85.  
  86. Name:
  87. -----
  88. The Name command sets the name of the icon as contained in the 'Special icon'
  89. submenu and in the Function names (described later), it must therefore comply
  90. with Basic V variable name restrictions.
  91. Note: Although the command is not case sensitive in this case the value is.
  92. Example:
  93. Name: Pointer
  94.  
  95. Author:
  96. -------
  97. You!
  98. This Command sets the name of the icon's author to be displayed in the Info
  99. Box for the icon.
  100. Example:
  101. Author: Fred Bloggs
  102.  
  103. Version:
  104. --------
  105. Sets the version number of the icon as displayed in the 'Info' box including
  106. the date, if required.
  107. Example:
  108. Version: 1.00 (19 Aug 1994)
  109.  
  110. Width:
  111. ------
  112. Sets the width of the icon in OS units. The value must be a decimal integer
  113. and a multiple of four.
  114. Example:
  115. Width: 100
  116.  
  117. Height:
  118. -------
  119. Sets the height of the icon in OS units. The value must be a decimal integer
  120. and a multiple of four.
  121. Example:
  122. Height: 100
  123.  
  124. Worksize:
  125. ---------
  126. Sets the amount of workspace the icon requires in bytes. The value must be a
  127. decimal integer.
  128. Example:
  129. Worksize: 100
  130.  
  131. Update:
  132. -------
  133. Defines how often the icon requires updating, the value must be one of the
  134. following words:
  135.  
  136. Continuous
  137. Second
  138. Minute
  139. Hour
  140. Day
  141. Never
  142.  
  143. A value of Continuous means the icon needs updating as often as possible.
  144. Pointer is an example of such an icon.
  145. A value of Second, Minute, Hour or Day mean the icon needs updating every
  146. Second, Minute, Hour or Day (what else!).
  147. Never means the icon's contents do not change with time and therefore it does
  148. not require updating. It is, however, updated whenever it receives a message,
  149. keypress or mouseclick.
  150.  
  151. Message_State:
  152. --------------
  153. Defines whether or not Wimp messages should be reported to the icon, the
  154. value must be either "On" or "Off".
  155.  
  156. Mouse_State:
  157. --------------
  158. Defines whether or not mouse clicks should be reported to the icon, the
  159. value must be either "On" or "Off".
  160.  
  161. Keypress_State:
  162. --------------
  163. Defines whether or not Keypresses should be reported to the icon, the
  164. value must be either "On" or "Off".
  165.  
  166. Menu_State:
  167. --------------
  168. Defines whether or not the icon has a menu associated with it, the value must
  169. be either "On" or "Off".
  170.  
  171. Start_Parameters
  172. ----------------
  173. Start_Parameters initiates the definition of parameters. It is followed by
  174. a list of parameter descriptions terminated by the Command "End_Parameters".
  175. Example:
  176. Start Parameters
  177.  
  178. A parameter description has the following format:
  179. |<Spaces>|<Name>:|<Spaces>|<default>
  180.  
  181. Where <name> is the name of the parameter (as displayed in the icons's
  182. submenu and <default> is its default value. As is initially displayed in
  183. the writeable parameter submenu item.
  184. Example:
  185. Pathname: adfs::4.$.Fred
  186.  
  187. Megaboard currently has a limit of 16 parameters per icon this will
  188. (hopefully) be altered in a later version.
  189.  
  190. End_Parameters
  191. --------------
  192. End_Parameters terminates a list of parameters.
  193.  
  194. Example of a parameter list:
  195. Start_Parameters
  196.   Pathname: adfs::4.$.Fred
  197.   Size: 1024
  198. End_Parameters
  199.  
  200. End_Icon
  201. --------
  202. End_icon terminates an icon definition
  203. Example:
  204. End_Icon
  205.  
  206. -------------------------
  207. - ARM code entry points -
  208. -------------------------
  209. A Megaboard special icon requires a file containing several blocks of ARM
  210. code function correctly. The file must have the following format:
  211.  
  212. Size of the first code block (including this word) (1 word)
  213. First code block (n words (must be a whol number of words))
  214.  
  215. Size of the second code block (1 word)
  216. Second code block (n words (must be a whol number of words))
  217.  
  218. ...
  219.  
  220. Size of the last code block (1 word)
  221. Last code block (n words (must be a whol number of words))
  222.  
  223. The following code blocks are required:
  224.   initialise
  225.   null
  226.   redraw
  227.   finish
  228.   save
  229.   load
  230.   message
  231.   mouse
  232.   key
  233.   menu
  234.   menu_select
  235.   menu_warning
  236. All of these blocks must be present in every entry points file regardless of
  237. whether a particular icon responds to all messages.
  238. Entry points are called using the BASIC CALL and USR commands i.e. R13 points
  239. to a stack and MOV PC,R14 Areturns.
  240. Entry point code must be position independent.
  241. The entry points file should be named "Code" and placed in the directory
  242. "!MegaBoard.Special.<icon name>". Where <icon name> is the name specified in
  243. the definition. Any other files the icon reqiures should also be stored in
  244. this directory.
  245.  
  246. Technical details of the entry points
  247. -------------------------------------
  248.  
  249.                            INITIALISE
  250.                            ----------
  251. On entry:
  252.  
  253.     R0 - The X screen coordinate of the centre of the icon.
  254.     R1 - The Y screen coordinate of the centre of the icon.
  255.     R2 - The width of the icon.
  256.     R3 - The height of the icon.
  257.     R4 - A pointer to the icon's workspace.
  258.     R5 - A pointer to a list of parameters
  259.          R5+0     - first parameter string
  260.          R5+256   - second parameter string
  261.                     ...
  262.          R5+n*256 - last parameter string
  263.  
  264. On exit:
  265.  
  266.     A% - New X screen coordinate
  267.     B% - New Y screen coordinate
  268.     C% - New icon width
  269.     D% - New icon height
  270.  
  271. Purpose:
  272.  
  273. Initialise is called when the icon is first placed on MegaBoard i.e. when the
  274. user clicks on it's menu item. It should do any setting up the icon requires
  275. in order for redraw to be called and store any parameters.
  276.  
  277. Note: the BASIC variables A%-D% are altered from assembler with the
  278.       following code (with A% as an example):
  279.  
  280.    ADR        R11,variable       ;R11 points to the variable name
  281.    STMFD      R13!,{R14}         ;presverve R14 on the stack
  282.    MOV        R10,R14            
  283.    ADR        R14,done           ;point R14 to the address BASIC's variable
  284.                                   locator should return to.
  285.    ADD        PC,R10,#&3C        ;call BASIC's variable locator
  286.  
  287.   .done                          ;R0 now points to