home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / utilities / utilsm / megaboard / Docs / ProgTutrl < prev    next >
Text File  |  1995-03-09  |  13KB  |  307 lines
  1.                 Tutorial for writing Special icons for Megaboard
  2.                 ------------------------------------------------
  3. ----------------
  4. - Introduction -
  5. ----------------
  6. This file explains in a step-by-step manner how to create a special icon that
  7. displays the current time, it will only be of interest to programmers, other
  8. users should refer to the "Guide" file for information on general use.
  9. For a full technical description of special icons see the ProgGuide file.
  10. Note: the icon defined here serves no practical use as it simply duplicates
  11. an icon already supplied with MegaBoard, but it is a good example of a
  12. typical special icon.
  13.  
  14. ----------------------------------
  15. - Part 1: Writing the definition -
  16. ----------------------------------
  17. Open the !MegaBoard application directory, locate the file 'Cstm_Scrpt', and
  18. load it into a text editor.
  19. Now add the following command to the end of the file:
  20.  
  21.   Start_Icon
  22.  
  23. This notifies MegaBoard that an icon definition begins here. The following
  24. lines must contain the commands descried in the 'ProgGuide' file i.e:
  25.  
  26.   Name: TutTime
  27. To specify the name of the icon
  28.  
  29.   Purpose: Display the current time
  30.   Author: Your Name
  31.   Version: 0.00
  32. These will be displayed in the special info dialogue box.
  33.  
  34.   Width: 150
  35. This sets the initial width of the icon to 150 OS units
  36.  
  37.   Height: 40
  38. This sets the initial height of the icon to 150 OS units
  39.  
  40.   Worksize: 1024
  41. Reserves 1024 bytes of workspace for the icon when it is created
  42.  
  43.   Update: Second
  44. Informs Megaboard that the icon requires updating every second
  45.  
  46.   Mouse_State: Off
  47.   Keypress_State: Off
  48.   Message_State: Off
  49.   Menu_State: Off
  50. The icon does not respond to mouse clicks, keypresses or Wimp messages and
  51. does not have a menu associated with it.
  52.  
  53.   Start_Parameters
  54.   Format: %z24:%mi:%se
  55.   End_Parameters
  56. States that the icon has one user-definable parameter called "Format" with
  57. the default value "%z24:%mi:%se".
  58.  
  59.   End_Icon
  60. Terminates the icon definition.
  61.  
  62. The icon definition should now look like this:
  63.   Start_Icon
  64.   Name: TutTime
  65.   Purpose: Display the current time
  66.   Author: Your Name
  67.   Version: 0.00
  68.   Width: 150
  69.   Height: 40
  70.   Worksize: 1024
  71.   Mouse_State: Off
  72.   Keypress_State: Off
  73.   Message_State: Off
  74.   Menu_State: Off
  75.   End_Icon
  76.  
  77. Now save the file and if it is not already running, run MegaBoard. The
  78. Special icon submenu should now contain an additional item, namely "TutTime".
  79. DO NOT CHOOSE THIS ITEM YET!!!
  80.  
  81.  
  82. -----------------------------------
  83. - Part 2: Writing the code blocks -
  84. -----------------------------------
  85. The BASIC file 'Skeleton' in this directory contains the source code of a
  86. "blank" special icon i.e. one that neither display anything nor responds to
  87. any events. Run this file, it will save the code file in the current
  88. directory.
  89. Open the directory !MegaBoard.Special and create a new diretory called
  90. "TutTime" (the same as the icon name) then locate the code file previously
  91. saved and copy it into this direcory.
  92. Now the icon's menu item in the 'Special icon' submenu can be chosen, but
  93. take care to note the location of the pointer when Menu was originally
  94. clicked or you will have difficulty locating the icon. An invisible icon will
  95. then be placed on MegaBoard, you can verify this by dragging Seelect or
  96. Adjust over the pointer position where menu was clicked, which should allow
  97. the icon represented by a 'rotating dash' box to to dragged around MegaBoard.
  98.  
  99. In order for the icon to do something meaningful the relevant code blocks
  100. will have to be written. Load the "Skeleton" file into a BASIC editor
  101.  
  102. A Code block in the skeleton file looks something like this:
  103.   REM initialise
  104.   EQUD init_end-P%
  105.   MOV PC,R14
  106.  .init_end
  107.  
  108. The file line after the REM inserts a word conatining the length of the
  109. block. Following this is the actual code, in this case it is simply a return
  110. instruction terminated by the label referred to in the EQUD.
  111.  
  112. 1. Initialise
  113. -------------
  114. In our example the initialisation code must simply copy the parameter string
  115. into the icon's own workspace, encoding is not necessary:
  116.  
  117.   .init       MOV    R7,#0          :REM set the offset to 0
  118.   .stringloop LDRB   R6,[R5],#1     :REM load a character into R6 and
  119.                                      REM increment R5
  120.               STRB   R6,[R4,R7]     :REM store the character in R4+R7
  121.               ADD    R7,R7,#1       :REM increment R7
  122.               CMP    R6,#32         :REM check if the character was a
  123.                                      REM terminator
  124.               BGE    stringloop     :REM if not then copy the next character
  125.               MOV    R6,#0          :REM replace the control terminator with
  126.               STRB   R6,[R4,R7]     :REM a null.
  127.  
  128. Next we have to read the curent time in a 5-byte format:
  129.  
  130.    ADD    R1,R4,#256   :REM the 5 bytes are stored at workspace offset 256
  131.    MOV    R0,#3
  132.    STR    R0,[R1]
  133.    MOV    R0,#14
  134.    SWI"OS_Word"
  135.  
  136. This 5-byte time information now needs to be converted ino a string:
  137.  
  138.    MOV      R0,R1                    :REM R0 points to the 5-byte time
  139.    ADD      R1,R0,#8                 :REM R1 points to the buffer for the
  140.                                       REM string at workspace offset 264
  141.                                       REM (i.e. 256+8)
  142.    MOV      R2,#240                  :REM buffer size
  143.    MOV      R3,R4                    :REM R3 points to the format string
  144.    STMFD    R13!,{R0-R3}             :REM push these registers to the stack
  145.                                      :REM because we need them later
  146.    SWI      "XOS_ConvertDateAndTime" :REM do not generate errors
  147.  
  148. If OS_ConvertDateAndTime detected an error in the format string it will
  149. return with the V flag set this must now be checked for and handled. If an
  150. error occurred the time and format strings will be replaced with the word
  151. "ERROR".
  152.  
  153.    MOV     R5,R0             :REM these registers will be needed if there was
  154.    MOV     R6,R1             :REM no error
  155.    LDMFD   R13!,{R0-R3}      :REM pull the registers from the stack that were
  156.                               REM stored above.
  157.  
  158.    REM the following is only executed if there was an error
  159.    LDRVS   R2,error1         :REM load the first 4 bytes of the word "ERROR"
  160.                               REM into R2
  161.    STRVS   R2,[R1]           :REM replace both the format string and the time
  162.    STRVS   R2,[R3]           :REM string with the word "ERROR"
  163.    LDRVS   R2,error2         :REM copy the second
  164.    STRVS   R2,[R1,#4]        :REM 4 bytes
  165.    STRVS   R2,[R3,#4]        :REM (actually only 2)
  166.    SUBVC   R1,R6,R5          :REM if there was no error set R1 to the length
  167.                               REM of the time string +1
  168.    MOVVS   R1,#6             :REM if there was an error set R1 to the length
  169.                               REM of "ERROR" +1 i.e. 6
  170.  
  171. Finally BASIC's C% variable must be modifed to the width of the of the string
  172. in OS units.
  173.  
  174.           SUB    R1,R1,#1        :REM subtract 1 from R1 to obtain the number
  175.                                   REM of characters
  176.           STR    R1,reg1         :REM save it because BASIC's locator code
  177.                                   REM corruptsR1 (not mentioned in the BASIC
  178.                                   REM guide!!)
  179.           ADR    R11,c           :REM point R11 to the string "C%"
  180.           STMFD  R13!,{R14}      :REM push the return address to the stack
  181.           MOV    R10,R14         :REM copy R14 to R10 because R14 is altered
  182.                                   REM in the next line
  183.           ADR    R14,done        :REM point R14 to the address the variable
  184.                                   REM locator should return to
  185.           ADD    PC,R10,#&3C      REM call the variable locator
  186.  
  187.    .done  LDRNE  R1,reg1         :REM reload the number of characters
  188.           MOVNE  R2,#16          :REM multiply the number characters 
  189.           MULNE  R1,R2,R1        :REM by 16 (the number of OS units per
  190.                                   REM system font character
  191.           STRNE  R1,[R0]         :REM store this value in the variable
  192.           LDMFD  R13!,{PC}       :REM return to BASIC
  193.  
  194.   .c      EQUS   "C%"+CHR$(10):ALIGN
  195.   .reg1   EQUD   0
  196.   .error1 EQUS   "ERRO"
  197.   .error2 EQUS   "R"+CHR$(0):ALIGN
  198.  
  199. Thi