home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / education / a / linguist / !Linguist / IntDocs < prev    next >
Text File  |  1990-12-09  |  25KB  |  655 lines
  1. *********************  Interface 1.30 (c) Simon Huntington ******************* 
  2.  
  3.  
  4. *********************************************************************************
  5. *********************************************************************************
  6. *********************************************************************************
  7. *********************************************************************************
  8. *                                                                               *
  9. * Modification : You now pass the task handle in R2 when using Wimp_PollPointer *
  10. *                                                                               *
  11. * Shading is now done with the light from the top left as in Impression II      *
  12. *                                                                               *
  13. *********************************************************************************
  14. *********************************************************************************
  15. *********************************************************************************
  16. *********************************************************************************
  17.  
  18. © Software Interrupt 1990
  19.  
  20.  
  21. This manual and software is public domain.  It may be copied and distributed freely 
  22. as long as:
  23.  
  24.        It is not separated from the documentation (except for commercial use)
  25.        The module is not tampered with
  26.        You do not claim that you have written the module
  27.  
  28. If you wish to use this in a commercial product please contact me so that I can make 
  29. sure you have the latest release, please send a disk.
  30.  
  31. In no circumstances shall the author be liable for any damage, loss of profits, time or 
  32. data or any indirect or consequential loss rising out of the use of this software or 
  33. inability to use this software.
  34.  
  35. Contacts:
  36.        Arcade BBS          (081 654 2212)                   
  37.        The World Of Cryton (0749 679794)     
  38.        Charron BBS         (0420 63115)
  39.        Noah BBS            (0272 572322)
  40.        MegaNet             (0924 223456)
  41.  
  42.        All mail on the above Bulletin Bords should be mailed to JICK
  43.  
  44.  
  45. A version of this document in Impression format can be obtained by sending a 
  46. blank disc and return postage to me.  I will also stick on a modified Formed
  47. to display Interface windows
  48.  
  49.  
  50. All correspondence should be addressed to:
  51.  
  52.         SoftWare Interrupt
  53.         40 Castle Ings Gardens
  54.         New Farnley
  55.         Leeds
  56.         LS12 5EG
  57.  
  58.  
  59. **************** Introduction ***********************************************
  60.  
  61. Interface is a small module that allows application programmers to implement a 
  62. colourful and pleasant graphical user interface.  Interface provides many more 
  63. functions that allows you to change the pointer shape easily and to interface with the 
  64. !Help or !Spy application.
  65.  
  66. The Interface module provides functions to improve the friendliness and appearance 
  67. of the application. The application should still operate as stated in  the Acorn 
  68. guidelines in the Programmers Reference Manuals.
  69.  
  70. The module implements a number of SWIs which are described further in this 
  71. manual, these SWI calls can be called from any language.  Most of the functions 
  72. provided are specified in the icons validation string, and so no complex 
  73. programming is needed to make the application look good.
  74.  
  75. This guide tells you how to fully implement the features of Interface.  It is split into 
  76. the follow sections:
  77.  
  78.         The first section explains the validation strings options provided
  79.         by Interface.
  80.         The next section gives details of the SWI calls provided.
  81.         The remaining section covers hints and tips on programming.
  82.  
  83.  
  84.  
  85.  
  86.  
  87.  
  88. **************** Technical details ***********************************************
  89.  
  90. An indirected text icon can have a validation string which is used to pass further 
  91. information to the WIMP, such as what border type the icon has and also what 
  92. pointer, if any should be displayed whilst over this icon.  The syntax of a validation 
  93. string is:
  94.  
  95.   validation string ::- command {;command}*
  96.   command           ::- b border-type {border-spec} | 
  97.                         r on/off-type {,icon-number}* |
  98.                         u on/off-type {,icon-number}* |
  99.                         p text-string {,x} {,y} |
  100.                         i text-string   
  101.   border-spec       ::- {,button-slabbing-mask} {,slabbing-time} {,colour}*
  102.  
  103. The parameters above are described under the relevant validation command.
  104. In simple terms, a validation string consists of a series of 'commands', each starting 
  105. with a single letter and seperated from the following command by a semi-colon.  
  106. {}* means zero or more of the thing inside the {}.  The following commands are 
  107. available with the Interface module.
  108.  
  109. These commands are provided in addition to the standard Wimp validation strings.  
  110. I suggest that you edit the !FormEd program to allow you to enter larger validation 
  111. strings, otherwise when entering a help command you will only be allowed a 
  112. maximum of 80 characters.
  113.  
  114. The (B)order command tells Interface which border to use when rendering an icon.  
  115. The border types available at present are :
  116.  
  117.         border type 0, this is a single border used mainly for headings and action icons.
  118.         The icon will slab inwards if the user clicks a button whilst the pointer is over 
  119.         the icon providing it is not setup to ignore mouse clicks.
  120.  
  121.         border type 1, this is a double border and should be used to group together 
  122.         icons that perform an operation.
  123.  
  124.         border type 2, this is a triple border and should be used on the default action         
  125.         button.  The icon will slab inwards when the user clicks a button whilst the 
  126.         pointer is over this icon providing it is not setup to ignore mouse clicks.
  127.  
  128.         border type 3, this is a wide inverted border and should be used on writable
  129.         icons.  This border type is usually used in-conjunction with the writable
  130.         pointer.
  131.  
  132. The second optional parameter is the button slabbing mask, this states whether the 
  133. icon should be slabbed until the button is released.  The values contained in this 
  134. parameter can be from 0 to 7.  The button slabbing mask can be calculated in the 
  135. following way:
  136.  
  137.         Value   Button          Meaning
  138.         1       Adjust  slab icon until adjust is released
  139.         2       Menu    slab icon until menu is released
  140.         4       Select  slab icon until select is released
  141.  
  142. The button slabbing mask can then be calculated by adding together the required 
  143. button values.  
  144.  
  145. The button slabbing time is the minimum time that the icon will be slabbed for, the 
  146. default time is for 15cs.  This value is a decimal number in centi-seconds.
  147. The colours are specified in the following order:
  148.  
  149.         {,border colour1} {,border colour2} {,slabbing out colour} 
  150.         {,slabbing in colour} {,inner channel colour}
  151.  
  152. These colours can be any valid WIMP colour in the range of 0 to 15, the default 
  153. selection is 4, 0, 1, 14, 12.
  154.  
  155. The (R)adio command specified in the validation string is used to set the state of 
  156. other radio button type icons.  The R command is followed by a decimal number in 
  157. the range 0 to 2, the action that these perform is:
  158.  
  159.         Radio type              Operation
  160.         0               this has the effect of switching off the specified icon(s).
  161.         1               this has the effect of switching on the specified icon(s).      
  162.         2               this has the effect of toggling the icons current state.
  163.  
  164. This command is then followed by the numbers of the icons you wish to alter, these 
  165. should be separated by commas.  This command may be specified more than once in 
  166. a validation string, for example to switch icons 1 & 2 off, 3 & 4 on and toggle the 
  167. state of icons 5 & 6 you could use the following validation string
  168.  
  169.         R0,1,2;R1,3,4;R2,5,6
  170.  
  171. The (U)nselectable command in the validation string has the effect of shading the 
  172. icon grey so that it cannot be selected by the user.  It is followed by a decimal 
  173. number in the range 0 to 2, the action that these is described above in the radio 
  174. command.
  175.  
  176. This command is then followed by the numbers of the icons you wish