home *** CD-ROM | disk | FTP | other *** search
/ APDL Public Domain 1 / APDL_PD1A.iso / customise / megaboard / Docs / ProgGuide < prev    next >
Encoding:
Text File  |  1994-12-19  |  17.5 KB  |  600 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 the
  106. 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. Example:
  114. Width: 100
  115.  
  116. Height:
  117. -------
  118. Sets the height of the icon in OS units. The value must be a decimal integer.
  119. Example:
  120. Height: 100
  121.  
  122. Worksize:
  123. ---------
  124. Sets the amount of workspace the icon requires in bytes. The value must be a
  125. decimal integer.
  126. Example:
  127. Worksize: 100
  128.  
  129. Update:
  130. -------
  131. Defines how often the icon requires updating, the value must be one of the
  132. following words:
  133.  
  134. Continuous
  135. Second
  136. Minute
  137. Hour
  138. Day
  139. Never
  140.  
  141. A value of Continuous means the icon needs updating as often as possible.
  142. Pointer is an example of such an icon.
  143. A value of Second, Minute, Hour or Day mean the icon needs updating every
  144. Second, Minute, Hour or Day (what else!).
  145. Never means the icon's contents do not change with time and therefore it does
  146. not require updating. It is, however, updated whenever it receives a message,
  147. keypress or mouseclick.
  148.  
  149. Message_State:
  150. --------------
  151. Defines whether or not Wimp messages should be reported to the icon, the
  152. value must be either "On" or "Off".
  153.  
  154. Mouse_State:
  155. --------------
  156. Defines whether or not mouse clicks should be reported to the icon, the
  157. value must be either "On" or "Off".
  158.  
  159. Keypress_State:
  160. --------------
  161. Defines whether or not Keypresses should be reported to the icon, the
  162. value must be either "On" or "Off".
  163.  
  164. Menu_State:
  165. --------------
  166. Defines whether or not the icon has a menu associated with it, the value must
  167. be either "On" or "Off".
  168.  
  169. Start_Parameters
  170. ----------------
  171. Start_Parameters initiates the definition of parameters. It is followed by
  172. a list of parameter descriptions terminated by the Command "End_Parameters".
  173. Example:
  174. Start Parameters
  175.  
  176. A parameter description has the following format:
  177. |<Spaces>|<Name>:|<Spaces>|<default>
  178.  
  179. Where <name> is the name of the parameter (as displayed in the icons's
  180. submenu and <default> is its default value. As is initially displayed in
  181. the writeable parameter submenu item.
  182. Example:
  183. Pathname: adfs::4.$.Fred
  184.  
  185. Megaboard currently has a limit of 16 parameters per icon this will
  186. (hopefully) be altered in a later version.
  187.  
  188. End_Parameters
  189. --------------
  190. End_Parameters terminates a list of parameters.
  191.  
  192. Example of a parameter list:
  193. Start_Parameters
  194.   Pathname: adfs::4.$.Fred
  195.   Size: 1024
  196. End_Parameters
  197.  
  198. End_Icon
  199. --------
  200. End_icon terminates an icon definition
  201. Example:
  202. End_Icon
  203.  
  204. -------------------------
  205. - ARM code entry points -
  206. -------------------------
  207. A Megaboard special icon requires a file containing several blocks of ARM
  208. code function correctly. The file must have the following format:
  209.  
  210. Size of the first code block (including this word) (1 word)
  211. First code block (n words (must be a whol number of words))
  212.  
  213. Size of the second code block (1 word)
  214. Second code block (n words (must be a whol number of words))
  215.  
  216. ...
  217.  
  218. Size of the last code block (1 word)
  219. Last code block (n words (must be a whol number of words))
  220.  
  221. The following code blocks are required:
  222.   initialise
  223.   null
  224.   redraw
  225.   finish
  226.   save
  227.   load
  228.   message
  229.   mouse
  230.   key
  231.   menu
  232.   menu_select
  233.   menu_warning
  234. All of these blocks must be present in every entry points file regardless of
  235. whether a particular icon responds to all messages.
  236. Entry points are called using the BASIC CALL and USR commands i.e. R13 points
  237. to a stack and MOV PC,R14 Areturns.
  238. Entry point code must be position independent.
  239. The entry points file should be named "Code" and placed in the directory
  240. "!MegaBoard.Special.<icon name>". Where <icon name> is the name specified in
  241. the definition. Any other files the icon reqiures should also be stored in
  242. this directory.
  243.  
  244. Technical details of the entry points
  245. -------------------------------------
  246.  
  247.                            INITIALISE
  248.                            ----------
  249. On entry:
  250.  
  251.     R0 - The X screen coordinate of the centre of the icon.
  252.     R1 - The Y screen coordinate of the centre of the icon.
  253.     R2 - The width of the icon.
  254.     R3 - The height of the icon.
  255.     R4 - A pointer to the icon's workspace.
  256.     R5 - A pointer to a list of parameters
  257.          R5+0     - first parameter string
  258.          R5+256   - second parameter string
  259.                     ...
  260.          R5+n*256 - last parameter string
  261.  
  262. On exit:
  263.  
  264.     A% - New X screen coordinate
  265.     B% - New Y screen coordinate
  266.     C% - New icon width
  267.     D% - New icon height
  268.  
  269. Purpose:
  270.  
  271. Initialise is called when the icon is first placed on MegaBoard i.e. when the
  272. user clicks on it's menu item. It should do any setting up the icon requires
  273. in order for redraw to be called and store any parameters.
  274.  
  275. Note: the BASIC variables A%-D% are altered from assembler with the
  276.       following code (with A% as an example):
  277.  
  278.    ADR        R11,variable       ;R11 points to the variable name
  279.    STMFD      R13!,{R14}         ;presverve R14 on the stack
  280.    MOV        R10,R14            
  281.    ADR        R14,done           ;point R14 to the address BASIC's variable
  282.                                   locator should return to.
  283.    ADD        PC,R10,#&3C        ;call BASIC's variable locator
  284.  
  285.   .done                          ;R0 now points to the variable's value
  286.    LDR        R1,newvalue
  287.    STR        R1,[R0]
  288.  
  289.   .variable EQUS A%+CHR$(10):ALIGN
  290.   .newvalue EQUD new_value%
  291.  
  292.  
  293.  
  294.  
  295.                                NULL
  296.                                ----
  297. On entry:
  298.  
  299.     R0 - The X screen coordinate of the centre of the icon.
  300.     R1 - The Y screen coordinate of the centre of the icon.
  301.     R2 - The width of the icon.
  302.     R3 - The height of the icon.
  303.     R4 - A pointer to the icon's workspace.
  304.  
  305. On exit:
  306.  
  307.     A% - New X screen coordinate
  308.     B% - New Y screen coordinate
  309.     C% - New icon width
  310.     D% - New icon height
  311.  
  312. Purpose:
  313.  
  314. Null is called if the icon's script file entry has not set its update state
  315. to "Never". Megaboard attempts to call it at the interval specified by the
  316. update state, this is, however not guaranteed.
  317.  
  318.  
  319.                                REDRAW
  320.                                ------
  321. On entry:
  322.  
  323.     R0 - The X screen coordinate of the centre of the icon.
  324.     R1 - The Y screen coordinate of the centre of the icon.
  325.     R2 - The width of the icon.
  326.     R3 - The height of the icon.
  327.     R4 - A pointer to the icon's workspace.
  328.  
  329. On exit:
  330.  
  331.      ---
  332.  
  333. Purpose:
  334.  
  335. Redraw is called whenever the icon on the screen requires updating, e.g. when
  336. all or part of it is uncovered by a moved window, and immediately after ALL
  337. other entry points except finish and those relating to menus. It should draw
  338. the icon at the screen coordinates in R0,R1.
  339.  
  340. Note: Some restrictions apply within this entry point:
  341.       - It is possible that screen output is redirected to a sprite when
  342.         redraw is called. If this is the case then OS_ReadModeVariable will
  343.         not return the correct values for the current mode, but for the
  344.         sprite.
  345.       - In order for the icon to be redrawn at the correct position redraw
  346.         is sometimes called with the graphics origin not at (0,0) most
  347.         RISC OS calls that output to the screen acknowledge this and modify
  348.         their output acordingly, Font_Paint, however, does not. Icons that
  349.         use outline fonts should read the graphics origin (it will still be
  350.         read correctly if output is redirected) and add it to the coordinates
  351.         passed to Font_Paint.
  352.       - Redraw should NEVER alter the icon's appearance. It is very likely
  353.         that redraw will be called several times for a single redraw
  354.         operation, if a call altered the icon's appearance then the section
  355.         plotted by the next call to redraw will not match the plotted by the
  356.         first.
  357.  
  358.                                FINISH
  359.                                ------
  360. On entry:
  361.  
  362.     R0 - The X screen coordinate of the centre of the icon.
  363.     R1 - The Y screen coordinate of the centre of the icon.
  364.     R2 - The width of the icon.
  365.     R3 - The height of the icon.
  366.     R4 - A pointer to the icon's workspace.
  367.  
  368. On exit:
  369.  
  370.      ---
  371.  
  372. Purpose:
  373.  
  374. Finish is called when the icon is removed from MegaBoard. It should free up
  375. any resources claimed by other entry points, e.g. release RMA blocks and
  376. dynamic areas, close open files etc.
  377.  
  378.                                  SAVE
  379.                                  ----
  380. On entry:
  381.  
  382.     R0 - The X screen coordinate of the centre of the icon.
  383.     R1 - The Y screen coordinate of the centre of the icon.
  384.     R2 - The width of the icon.
  385.     R3 - The height of the icon.
  386.     R4 - A pointer to the icon's workspace.
  387.     R5 - Handle of the save file
  388.  
  389. On exit:
  390.  
  391.     R0 - Number of saved parameters
  392.  
  393. Purpose:
  394.  
  395. Save is called when the user saves MegaBoard's current state to disc. If the
  396. icon has not altered it's state since initialisation this entry point should
  397. simply return with R0=0. Otherwise it should save a set of parameter strings
  398. it requires to reconstruct its current state in the save file. The format of 
  399. these strings is:
  400.  
  401. [<spaces>]<n>:[<spaces>]<string><newline>
  402.  
  403. Where n is a number between 1 and the number returned in R5 (inclusive). The
  404. precise number of parameters returned in R5 must also be saved to the file
  405. and each must be uniquely numbered, however, they need not be stored in
  406. order.
  407. These parameters should not be confused with the icon's parameters specified
  408. in the icon's definition, although the strings may be the same.
  409. The number of saved parameters is not limited.
  410.  
  411.                                  LOAD
  412.                                  ----
  413. On entry:
  414.  
  415.     R0 - The X screen coordinate of the centre of the icon.
  416.     R1 - The Y screen coordinate of the centre of the icon.
  417.     R2 - The width of the icon.
  418.     R3 - The height of the icon.
  419.     R4 - A pointer to the icon's workspace.
  420.     R5 - Number of the saved parameter (-1 if there were none)
  421.     R6 - Pointer to the string (without the header)
  422.  
  423. On exit:
  424.  
  425.     A% - New X screen coordinate
  426.     B% - New Y screen coordinate
  427.     C% - New icon width
  428.     D% - New icon height
  429.  
  430. Purpose:
  431.  
  432. Load is called once for each saved parameter when the user loads a new state
  433. from disc or once only if no parameters were saved. When a new state is
  434. loaded the special icons' initialise entry points are not called, therefore
  435. load must perform any initialisation necessary.
  436. The parameters passed to load are in the order of their numbers, as stored by
  437. save not in the order in which they were saved. Therefore the last call will
  438. contain the highest number in R5.
  439.  
  440.  
  441.                                  MESSAGE
  442.                                  -------
  443. On entry:
  444.  
  445.     R0 - The X screen coordinate of the centre of the icon.
  446.     R1 - The Y screen coordinate of the centre of the icon.
  447.     R2 - The width of the icon.
  448.     R3 - The height of the icon.
  449.     R4 - A pointer to the icon's workspace.
  450.     R5 - A pointer to the message block
  451.  
  452. On exit:
  453.  
  454.     A% - New X screen coordinate
  455.     B% - New Y screen coordinate
  456.     C% - New icon width
  457.     D% - New icon height
  458.  
  459. Purpose:
  460.  
  461. Message is called if the icon's message state is set to "on" in it's
  462. definition and a file is dragged to the icon (i.e. Megaboard receices a
  463. DataLoad Message). R5 points to a standard message block as described in the
  464. PRM.
  465. Note: At the moment MegaBoard only passes DataLoad Messages on to special
  466.       icons, this may however change in future versions, this entry point 
  467.       should therefore first check whether the message is really a DataLoad.
  468.  
  469.                                  MOUSE
  470.                                  -----
  471. On entry:
  472.  
  473.     R0 - The X screen coordinate of the centre of the icon.
  474.     R1 - The Y screen coordinate of the centre of the icon.
  475.     R2 - The width of the icon.
  476.     R3 - The height of the icon.
  477.     R4 - A pointer to the icon's workspace.
  478.     R5 - Button state
  479.  
  480. On exit:
  481.  
  482.     A% - New X screen coordinate
  483.     B% - New Y screen coordinate
  484.     C% - New icon width
  485.     D% - New icon height
  486.  
  487. Purpose:
  488.  
  489. Mouse is called if the icon's mouse state is set to "on" in it's definition
  490. and the user clicks either Select or Adjust on the icon.
  491.  
  492.  
  493.                                    KEY
  494.                                    ---
  495. On entry:
  496.  
  497.     R0 - The X screen coordinate of the centre of the icon.
  498.     R1 - The Y screen coordinate of the centre of the icon.
  499.     R2 - The width of the icon.
  500.     R3 - The height of the icon.
  501.     R5 - Wimp Key code
  502.  
  503. On exit:
  504.  
  505.     A% - New X screen coordinate
  506.     B% - New Y screen coordinate
  507.     C% - New icon width
  508.     D% - New icon height
  509.  
  510. Purpose:
  511.  
  512. Key is called if the icon's key state is set to "on" in it's definition and
  513. the user presses a key not processed by other tasks.
  514.  
  515.                                    MENU
  516.                                    ----
  517. On entry:
  518.  
  519.     R0 - The X screen coordinate of the centre of the icon.
  520.     R1 - The Y screen coordinate of the centre of the icon.
  521.     R2 - The width of the icon.
  522.     R3 - The height of the icon.
  523.     R4 - A pointer to the icon's workspace.
  524.     R5 - X coordinate at which the menu should be opened.
  525.     R6 - Y coordinate at which the menu should be opened.
  526.  
  527. On exit:
  528.  
  529.    ---
  530.  
  531. Purpose:
  532.  
  533. This entry point is called if the icon's menu state is set to "on" in it's
  534. definition and the user moves the pointer over the "Special menu" arrow in
  535. the "Special" submenu. It should set up a menu block and open the menu with
  536. Wimp_CreateSubMenu (NOT Wimp_CreateMenu) at the coordinates specified in R5
  537. and R6.
  538.  
  539.  
  540.  
  541.  
  542.                                    MENU SELECT
  543.                                    -----------
  544. On entry:
  545.  
  546.     R0 - The X screen coordinate of the centre of the icon.
  547.     R1 - The Y screen coordinate of the centre of the icon.
  548.     R2 - The width of the icon.
  549.     R3 - The height of the icon.
  550.     R4 - Pointer to the icon's workspace.
  551.     R5 - Pointer to a block
  552.            R5+0 - Item in the icon's base menu that was selected
  553.            R5+4 - Item in the first submenu that was selected
  554.                              ...
  555.                   terminated by -1
  556.  
  557. On exit:
  558.  
  559.    ---
  560.  
  561. Purpose:
  562.  
  563. Menu select is called if the icon's menu state is set to "on" in it's
  564. definition and the user chooses an item from one of its menu.
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.                                    MENU WARNING
  572.                                    ------------
  573. On entry:
  574.  
  575.     R0 - The X screen coordinate of the centre of the icon.
  576.     R1 - The Y screen coordinate of the centre of the icon.
  577.     R2 - The width of the icon.
  578.     R3 - The height of the icon.
  579.     R4 - Pointer to the icon's workspace.
  580.     R5 - X coordinate where the submenu should be opened
  581.     R6 - Y coordinate where the submenu should be opened
  582.     R7 - Pointer to a block
  583.            R7+0 - Item in the icon's base menu that was selected
  584.            R7+4 - Item in the first submenu that was selected
  585.                              ...
  586.                   terminated by -1
  587.  
  588. On exit:
  589.  
  590.    ---
  591.  
  592. Purpose:
  593.  
  594. Menu warning is called if the icon's menu state is set to "on" in it's
  595. definition and MegaBoard receives a Menu_Warning message from the Wimp that
  596. is applicable to the icon's menu the user chooses an item from one of its
  597. menu.
  598.  
  599.  
  600.