home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / utilities / utilsm / megaboard / Docs / ProgGuide < prev    next >
Encoding:
Text File  |  1995-03-30  |  18.1 KB  |  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 the variable's value
  288.    LDR        R1,newvalue
  289.    STR        R1,[R0]
  290.  
  291.   .variable EQUS A%+CHR$(10):ALIGN
  292.   .newvalue EQUD new_value%
  293.  
  294.  
  295.  
  296.  
  297.                                NULL
  298.                                ----
  299. On entry:
  300.  
  301.     R0 - The X screen coordinate of the centre of the icon.
  302.     R1 - The Y screen coordinate of the centre of the icon.
  303.     R2 - The width of the icon.
  304.     R3 - The height of the icon.
  305.     R4 - A pointer to the icon's workspace.
  306.  
  307. On exit:
  308.  
  309.     A% - New X screen coordinate
  310.     B% - New Y screen coordinate
  311.     C% - New icon width
  312.     D% - New icon height
  313.  
  314. Purpose:
  315.  
  316. Null is called if the icon's script file entry has not set its update state
  317. to "Never". Megaboard attempts to call it at the interval specified by the
  318. update state, this is, however not guaranteed.
  319.  
  320.  
  321.                                REDRAW
  322.                                ------
  323. On entry:
  324.  
  325.     R0 - The X screen coordinate of the centre of the icon.
  326.     R1 - The Y screen coordinate of the centre of the icon.
  327.     R2 - The width of the icon.
  328.     R3 - The height of the icon.
  329.     R4 - A pointer to the icon's workspace.
  330.  
  331. On exit:
  332.  
  333.      ---
  334.  
  335. Purpose:
  336.  
  337. Redraw is called whenever the icon on the screen requires updating, e.g. when
  338. all or part of it is uncovered by a moved window, and immediately after ALL
  339. other entry points except finish and those relating to menus. It should draw
  340. the icon at the screen coordinates in R0,R1.
  341.  
  342. Note: Some restrictions apply within this entry point:
  343.       - It is possible that screen output is redirected to a sprite when
  344.         redraw is called. If this is the case then OS_ReadModeVariable will
  345.         not return the correct values for the current mode, but for the
  346.         sprite.
  347.       - In order for the icon to be redrawn at the correct position redraw
  348.         is sometimes called with the graphics origin not at (0,0) most
  349.         RISC OS calls that output to the screen acknowledge this and modify
  350.         their output acordingly, Font_Paint, however, does not. Icons that
  351.         use outline fonts should read the graphics origin (it will still be
  352.         read correctly if output is redirected) and add it to the coordinates
  353.         passed to Font_Paint.
  354.       - Redraw should NEVER alter the icon's appearance. It is very likely
  355.         that redraw will be called several times for a single redraw
  356.         operation, if a call altered the icon's appearance then the section
  357.         plotted by the next call to redraw will not match the plotted by the
  358.         first.
  359.  
  360.                                FINISH
  361.                                ------
  362. On entry:
  363.  
  364.     R0 - The X screen coordinate of the centre of the icon.
  365.     R1 - The Y screen coordinate of the centre of the icon.
  366.     R2 - The width of the icon.
  367.     R3 - The height of the icon.
  368.     R4 - A pointer to the icon's workspace.
  369.  
  370. On exit:
  371.  
  372.      ---
  373.  
  374. Purpose:
  375.  
  376. Finish is called when the icon is removed from MegaBoard. It should free up
  377. any resources claimed by other entry points, e.g. release RMA blocks and
  378. dynamic areas, close open files etc.
  379.  
  380.                                  SAVE
  381.                                  ----
  382. On entry:
  383.  
  384.     R0 - The X screen coordinate of the centre of the icon.
  385.     R1 - The Y screen coordinate of the centre of the icon.
  386.     R2 - The width of the icon.
  387.     R3 - The height of the icon.
  388.     R4 - A pointer to the icon's workspace.
  389.     R5 - Handle of the save file
  390.  
  391. On exit:
  392.  
  393.     R0 - Number of saved parameters
  394.  
  395. Purpose:
  396.  
  397. Save is called when the user saves MegaBoard's current state to disc. If the
  398. icon has not altered it's state since initialisation this entry point should
  399. simply return with R0=0. Otherwise it should save a set of parameter strings
  400. it requires to reconstruct its current state in the save file. The format of 
  401. these strings is:
  402.  
  403. [<spaces>]<n>:[<spaces>]<string><newline>
  404.  
  405. Where n is a number between 1 and the number returned in R5 (inclusive). The
  406. precise number of parameters returned in R5 must also be saved to the file
  407. and each must be uniquely numbered, however, they need not be stored in
  408. order.
  409. These parameters should not be confused with the icon's parameters specified
  410. in the icon's definition, although the strings may be the same.
  411. The number of saved parameters is not limited.
  412.  
  413.                                  LOAD
  414.                                  ----
  415. On entry:
  416.  
  417.     R0 - The X screen coordinate of the centre of the icon.
  418.     R1 - The Y screen coordinate of the centre of the icon.
  419.     R2 - The width of the icon.
  420.     R3 - The height of the icon.
  421.     R4 - A pointer to the icon's workspace.
  422.     R5 - Number of the saved parameter (-1 if there were none)
  423.     R6 - Pointer to the string (without the header)
  424.  
  425. On exit:
  426.  
  427.     A% - New X screen coordinate
  428.     B% - New Y screen coordinate
  429.     C% - New icon width
  430.     D% - New icon height
  431.  
  432. Purpose:
  433.  
  434. Load is called once for each saved parameter when the user loads a new state
  435. from disc or once only if no parameters were saved. When a new state is
  436. loaded the special icons' initialise entry points are not called, therefore
  437. load must perform any initialisation necessary.
  438. The parameters passed to load are in the order of their numbers, as stored by
  439. save not in the order in which they were saved. Therefore the last call will
  440. contain the highest number in R5.
  441.  
  442.  
  443.                                  MESSAGE
  444.                                  -------
  445. On entry:
  446.  
  447.     R0 - The X screen coordinate of the centre of the icon.
  448.     R1 - The Y screen coordinate of the centre of the icon.
  449.     R2 - The width of the icon.
  450.     R3 - The height of the icon.
  451.     R4 - A pointer to the icon's workspace.
  452.     R5 - A pointer to the message block
  453.  
  454. On exit:
  455.  
  456.     A% - New X screen coordinate
  457.     B% - New Y screen coordinate
  458.     C% - New icon width
  459.     D% - New icon height
  460.  
  461. Purpose:
  462.  
  463. Message is called if the icon's message state is set to "on" in it's
  464. definition and MegaBoard receives a WIMP message that is passed to special
  465. icons. R5 points to a standard message block as described in the PRM.
  466.  
  467. Currently the following messages are passed:
  468.   DataLoad (Only if the file is actually dropped on the icon)
  469.   ModeChange
  470.   IconDragged
  471. Note: Strictly speaking IconDragged is not a WIMP message, but a message
  472.       passed by MegaBoard to a special icon that has been dragged by the
  473.       user.
  474.       I have applied to Acorn for a message chunk allocation, but have yet to
  475.       receive a reply, so until then the message code for IconDragged is
  476.       &F00000, which is hopefully a long way outside currently allocated
  477.       message number space.
  478.  
  479. Note: At the moment MegaBoard only passes DataLoad Messages on to special
  480.       icons, this may however change in future versions, this entry point 
  481.       should therefore first check whether the message is really a DataLoad.
  482.  
  483.  
  484.                                  MOUSE
  485.                                  -----
  486. On entry:
  487.  
  488.     R0 - The X screen coordinate of the centre of the icon.
  489.     R1 - The Y screen coordinate of the centre of the icon.
  490.     R2 - The width of the icon.
  491.     R3 - The height of the icon.
  492.     R4 - A pointer to the icon's workspace.
  493.     R5 - Button state
  494.  
  495. On exit:
  496.  
  497.     A% - New X screen coordinate
  498.     B% - New Y screen coordinate
  499.     C% - New icon width
  500.     D% - New icon height
  501.  
  502. Purpose:
  503.  
  504. Mouse is called if the icon's mouse state is set to "on" in it's definition
  505. and the user clicks either Select or Adjust on the icon.
  506.  
  507.  
  508.                                    KEY
  509.                                    ---
  510. On entry:
  511.  
  512.     R0 - The X screen coordinate of the centre of the icon.
  513.     R1 - The Y screen coordinate of the centre of the icon.
  514.     R2 - The width of the icon.
  515.     R3 - The height of the icon.
  516.     R5 - Wimp Key code
  517.  
  518. On exit:
  519.  
  520.     A% - New X screen coordinate
  521.     B% - New Y screen coordinate
  522.     C% - New icon width
  523.     D% - New icon height
  524.  
  525. Purpose:
  526.  
  527. Key is called if the icon's key state is set to "on" in it's definition and
  528. the user presses a key not processed by other tasks.
  529.  
  530.                                    MENU
  531.                                    ----
  532. On entry:
  533.  
  534.     R0 - The X screen coordinate of the centre of the icon.
  535.     R1 - The Y screen coordinate of the centre of the icon.
  536.     R2 - The width of the icon.
  537.     R3 - The height of the icon.
  538.     R4 - A pointer to the icon's workspace.
  539.     R5 - X coordinate at which the menu should be opened.
  540.     R6 - Y coordinate at which the menu should be opened.
  541.  
  542. On exit:
  543.  
  544.    ---
  545.  
  546. Purpose:
  547.  
  548. This entry point is called if the icon's menu state is set to "on" in it's
  549. definition and the user moves the pointer over the "Special menu" arrow in
  550. the "Special" submenu. It should set up a menu block and open the menu with
  551. Wimp_CreateSubMenu (NOT Wimp_CreateMenu) at the coordinates specified in R5
  552. and R6.
  553.  
  554.  
  555.  
  556.  
  557.                                    MENU SELECT
  558.                                    -----------
  559. On entry:
  560.  
  561.     R0 - The X screen coordinate of the centre of the icon.
  562.     R1 - The Y screen coordinate of the centre of the icon.
  563.     R2 - The width of the icon.
  564.     R3 - The height of the icon.
  565.     R4 - Pointer to the icon's workspace.
  566.     R5 - Pointer to a block
  567.            R5+0 - Item in the icon's base menu that was selected
  568.            R5+4 - Item in the first submenu that was selected
  569.                              ...
  570.                   terminated by -1
  571.  
  572. On exit:
  573.  
  574.    ---
  575.  
  576. Purpose:
  577.  
  578. Menu select is called if the icon's menu state is set to "on" in it's
  579. definition and the user chooses an item from one of its menu.
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.                                    MENU WARNING
  587.                                    ------------
  588. On entry:
  589.  
  590.     R0 - The X screen coordinate of the centre of the icon.
  591.     R1 - The Y screen coordinate of the centre of the icon.
  592.     R2 - The width of the icon.
  593.     R3 - The height of the icon.
  594.     R4 - Pointer to the icon's workspace.
  595.     R5 - X coordinate where the submenu should be opened
  596.     R6 - Y coordinate where the submenu should be opened
  597.     R7 - Pointer to a block
  598.            R7+0 - Item in the icon's base menu that was selected
  599.            R7+4 - Item in the first submenu that was selected
  600.                              ...
  601.                   terminated by -1
  602.  
  603. On exit:
  604.  
  605.    ---
  606.  
  607. Purpose:
  608.  
  609. Menu warning is called if the icon's menu state is set to "on" in it's
  610. definition and MegaBoard receives a Menu_Warning message from the Wimp that
  611. is applicable to the icon's menu the user chooses an item from one of its
  612. menu.
  613.  
  614.  
  615.