home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / timing / a268_1 / !CHARGES / RESOURCES / Interface? < prev    next >
Text File  |  1992-07-22  |  23KB  |  606 lines
  1. Interface 2.00 
  2. © Software Interrupt 1990
  3.  
  4. See notes at end for update info......
  5.  
  6. This manual and software is public domain.  It may be copied and distributed freely 
  7. as long as:
  8.  
  9.        It is not separated from the documentation (except for commercial use)
  10.        The module is not tampered with
  11.        You do not claim that you have written the module
  12.        Do not use any of the code contained in this module in your own code
  13.  
  14. If you wish to use this in a commercial product please contact me so that I can make 
  15. sure you have the latest release, please send a disk.
  16.  
  17. In no circumstances shall the author be liable for any damage, loss of profits, time or 
  18. data or any indirect or consequential loss rising out of the use of this software or 
  19. inability to use this software.
  20.  
  21. Contacts:
  22.        Arcade BBS          (081 654 2212)                   
  23.        The World Of Cryton (0749 679794)     
  24.  
  25.        All mail on the above Bulletin Bords should be mailed to JICK
  26.  
  27. **************** Introduction ***********************************************
  28.  
  29. Interface is a small module that allows application programmers to implement a 
  30. colourful and pleasant graphical user interface.  Interface provides many more 
  31. functions that allows you to change the pointer shape easily and to interface with the 
  32. !Help or !Spy application.
  33.  
  34. The Interface module provides functions to improve the friendliness and appearance 
  35. of the application. The application should still operate as stated in  the Acorn 
  36. guidelines in the Programmers Reference Manuals.
  37.  
  38. The module implements a number of SWIs which are described further in this 
  39. manual, these SWI calls can be called from any language.  Most of the functions 
  40. provided are specified in the icons validation string, and so no complex 
  41. programming is needed to make the application look good.
  42.  
  43. This guide tells you how to fully implement the features of Interface.  It is split into 
  44. the follow sections:
  45.  
  46.         The first section explains the validation strings options provided
  47.         by Interface.
  48.         The next section gives details of the SWI calls provided.
  49.         The remaining section covers hints and tips on programming.
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56. **************** Technical details ***********************************************
  57.  
  58. An indirected text icon can have a validation string which is used to pass further 
  59. information to the WIMP, such as what border type the icon has and also what 
  60. pointer, if any should be displayed whilst over this icon.  The syntax of a validation 
  61. string is:
  62.  
  63.   validation string ::- command {;command}*
  64.   command           ::- (b | z) border-type {border-spec} | 
  65.                         r on/off-type {,icon-number}* |
  66.                         u on/off-type {,icon-number}* |
  67.                         p text-string {,x} {,y} |
  68.                         i text-string |
  69.                         k key-code
  70.   border-spec       ::- {,button-slabbing-mask} {,slabbing-time} {,colour}*
  71.  
  72. The parameters above are described under the relevant validation command.
  73. In simple terms, a validation string consists of a series of 'commands', each starting 
  74. with a single letter and seperated from the following command by a semi-colon.  
  75. {}* means zero or more of the thing inside the {}.  The following commands are 
  76. available with the Interface module.
  77.  
  78. These commands are provided in addition to the standard Wimp validation strings.  
  79. I suggest that you edit the !FormEd program to allow you to enter larger validation 
  80. strings, otherwise when entering a help command you will only be allowed a 
  81. maximum of 80 characters.
  82.  
  83. The (B)order command tells Interface which border to use when rendering an icon.  
  84. The border types available at present are :
  85.  
  86.         border type 0, this is a single border used mainly for headings and action icons.
  87.         The icon will slab inwards if the user clicks a button whilst the pointer is over 
  88.         the icon providing it is not setup to ignore mouse clicks.
  89.  
  90.         border type 1, this is a double border and should be used to group together 
  91.         icons that perform an operation.
  92.  
  93.         border type 2, this is a triple border and should be used on the default action         
  94.         button.  The icon will slab inwards when the user clicks a button whilst the 
  95.         pointer is over this icon providing it is not setup to ignore mouse clicks.
  96.  
  97.         border type 3, this is a wide inverted border and should be used on writable
  98.         icons.  This border type is usually used in-conjunction with the writable
  99.         pointer.
  100.         
  101.         border type 4, this is an inverted version of border type 0
  102.         
  103.         border type 5, this is a double wide border as used by acorn in ros 3
  104.         
  105.         border type 6, etched in border
  106.         
  107.         border type 7, similar to border type 0, thinner in mode 20
  108.  
  109. The second optional parameter is the button slabbing mask, this states whether the 
  110. icon should be slabbed until the button is released.  The values contained in this 
  111. parameter can be from 0 to 7.  The button slabbing mask can be calculated in the 
  112. following way:
  113.  
  114.         Value   Button          Meaning
  115.         1       Adjust  slab icon until adjust is released
  116.         2       Menu    slab icon until menu is released
  117.         4       Select  slab icon until select is released
  118.  
  119. The button slabbing mask can then be calculated by adding together the required 
  120. button values.  
  121.  
  122. The button slabbing time is the minimum time that the icon will be slabbed for, the 
  123. default time is for 15cs.  This value is a decimal number in centi-seconds.
  124. The colours are specified in the following order:
  125.  
  126.         {,border colour1} {,border colour2} {,slabbing out colour} 
  127.         {,slabbing in colour} {,inner channel colour}
  128.  
  129. These colours can be any valid WIMP colour in the range of 0 to 15, the default 
  130. selection is 4, 0, 1, 14, 12.
  131.  
  132. The (R)adio command specified in the validation string is used to set the state of 
  133. other radio button type icons.  The R command is followed by a decimal number in 
  134. the range 0 to 2, the action that these perform is:
  135.  
  136.         Radio type              Operation
  137.         0               this has the effect of switching off the specified icon(s).
  138.         1               this has the effect of switching on the specified icon(s).      
  139.         2               this has the effect of toggling the icons current state.
  140.  
  141. This command is then followed by the numbers of the icons you wish to alter, these 
  142. should be separated by commas.  This command may be specified more than once in 
  143. a validation string, for example to switch icons 1 & 2 off, 3 & 4 on and toggle the 
  144. state of icons 5 & 6 you could use the following validation string
  145.  
  146.         R0,1,2;R1,3,4;R2,5,6
  147.  
  148. The (U)nselectable command in the validation string has the effect of shading the 
  149. icon grey so that it cannot be selected by the user.  It is followed by a decimal 
  150. number in the range 0 to 2, the action that these is described above in the radio 
  151. command.
  152.  
  153. This command is then followed by the numbers of the icons you wish to alter, these 
  154. should be separated by commas.  This command may be specified more than once in 
  155. a validation string, for example to shade icons 1 & 2, un-shade 3 & 4 and toggle the 
  156. state of icons 5 & 6 you could use the following validation string
  157.  
  158.         U0,1,2;U1,3,4;U2,5,6
  159.  
  160. The (P)ointer command is used to define a pointer to be displayed when the pointer 
  161. is over that icon.  The first parameter is a sprite name to use for the pointer, this 
  162. should be no longer than 12 characters and should be present in the WIMP sprite 
  163. pool.  The optional parameters specify the x and y offsets to the active point in the 
  164. sprite, these should be specified in pixels.
  165.  
  166. The (I)nformation command is used to define a message to be sent to the interactive 
  167. help application when the pointer is over the icon.  If you wish to use a semi-colon 
  168. then you must place two next to each other.  The maximum length of the help 
  169. message is 235 characters.
  170.  
  171. The Interface module will change to the specified pointer when the mouse pointer is 
  172. over the icon/workarea, if no pointer is specified then the pointer will default to 
  173. shape one (the default arrow shape).  There are 5 pointer shapes designed in the 
  174. sprite file in the !Interface directory, these are:
  175.  
  176.         ptr_write - this pointer should be used on writable icons, the suggested active
  177.         point is at coordinates x = 4, y = 4.
  178.  
  179.         ptr_menu - this pointer is used where a menu can be activated by pressing the
  180.         menu button over the icon.  This stops the user having to search all over the
  181.         window to find where the menu is. The suggested active point is x = 6, y = 5.
  182.  
  183.         ptr_direct - this pointer is used where an object may be re-sized, the suggested
  184.         active point is at x = 13, y = 7.
  185.  
  186.         ptr_hand - this pointer is used where and icon may be dragged.  It is usually set
  187.         on the workarea, but it can be used on any icon (the save file icon looks great
  188.         when using it), its suggested active point is at x = 12, y = 8.
  189.  
  190.         ptr_cross - this pointer is used as a crosshair, it is the same as the one used in the
  191.         Draw application.  This icon gives the user a precise point when working with
  192.         line drawings, its suggested active point is at x = 13, y = 7.
  193.  
  194. You may also design your own pointers, which should be loaded into the WIMP 
  195. sprite pool.  There are a few points that you should note when designing pointers 
  196. these are :
  197.  
  198.         Pointer sprite names should have the form ptr_XXXXX, although this is not
  199.         compulsory it helps so that you do not get confused with pointers and normal
  200.         sprites.
  201.  
  202.         Do not use logical colour 2 in the pointer sprites, as this is unavailable in very
  203.         high resolution modes.
  204.  
  205. The pointers used should only be valid in your application, so you must not mask 
  206. out the Pointer_Leaving_Window in your application.  You should claim 
  207. Null_Reason_Code when passed to your application, otherwise the pointer will not 
  208. change when the pointer is over the icon/workarea, see the examples for more.
  209.  
  210. You should support the !Help application to help new users using your application, 
  211. this is why I implemented a feature in Interface to make this easier.  The following 
  212. was for some reason not published in the Programmers Reference Manuals, but was 
  213. in the pre-release disc version of the manuals.
  214.  
  215. For an application to use interactive help, two WIMP messages are employed.  One 
  216. is used by the Help to request help, and the other is used by the application to return 
  217. the help message.
  218.  
  219. To request help, the Help application sends a message of the following form:
  220.  
  221. block   +16     &502 - indicates request for help
  222.                 +20     mouse x co-ordinate
  223.                 +24     mouse y co-ordinate
  224.                 +28     mouse button state
  225.                 +32     window handle               (-1 if not over a window)
  226.                 +36     icon handle                 (-1 if not over an icon)
  227.  
  228. The WIMP system will pass this message automatically to the task in charge of the 
  229. appropriate window/icon.  If the application receiving the message wishes to produce 
  230. some help, it should respond with the following message:
  231.  
  232. block   +16     &503
  233.                 +20     help message terminated by 0
  234.  
  235. This message can be sent to the Help application by using Wimp_SendHelp, which 
  236. is provided by the Interface module (SWI &81687).
  237.  
  238. The help text may  contain any printable character codes.  If the sequence |M is 
  239. encountered then this will be treated as a line break and subsequent text will be 
  240. printed on the next line in the window.  If the text is too long for one line then it will 
  241. be split at a word boundary (space character).
  242.  
  243. The text should consist of  simple complete English sentences, each starting on a 
  244. new line and ending with a full stop.  The sentences should usually be simple 
  245. imperatives or information such as:
  246.  
  247.         Click SELECT to set the alarm.
  248.  
  249.         You are in Select mode.
  250.  
  251.         Click ADJUST to change to path edit mode.
  252.  
  253.         This is the icon for Edit.
  254.  
  255. In general you need not mention menu entries, except when specific ones interact 
  256. with pointer operations.  As a general rule present information of interest to the 
  257. beginner near the top, and expert tips or information lower down.
  258.  
  259. You must use the terminology defined.  For mouse operations you must use initial 
  260. capitals (for example Click).  The mouse buttons must be in capitals (for example 
  261. SELECT), as must key names (for example ESC, RETURN, SHIFT, CONTROL, A, B, F1, 
  262. COPY).  miss out speedups and shortcuts - just provide enough to help a beginner 
  263. without drowning them with information.
  264.  
  265. Provide interactive help thoroughly - include the icon bar, and the workarea of all 
  266. your windows.  If no actions are possible in a window, just
  267.  
  268.         This window shows....
  269.  
  270. if better than nothing.
  271.  
  272. You should assume a user knows:
  273.  
  274.         what a MENU key is
  275.         how to navigate menu trees and choose entries
  276.         what the icon bar is
  277.         how to move/size/toggle/close windows, and so on
  278.         what 'dragging an icon' means
  279.         what 'filling in a field' (writable icon) means
  280.  
  281. The keycode command should be placed in the icon that is activated by the 
  282. keycode.  It should be a decimal integer specifying the key.  The up/down
  283. arrows, tab etc.. are dealt with.
  284.  
  285.  
  286. **************************** The SWI Calls *********************************
  287.  
  288. Wimp_BorderIcon (Interface_SlabButton) (SWI &81680)
  289.  
  290. R1 = pointer to block
  291. R1 preserved
  292.  
  293. Interrupts are not defined
  294. Fast interrupts are enabled
  295.  
  296. Processor is in SVC mode
  297.  
  298. SWI is not re-entrant
  299.  
  300. The block contains the following on entry:
  301.  
  302.         R1+0    mouse x (screen coordinates - not window relative)
  303.         R1+4    mouse y
  304.         R1+8    buttons (depending on icon button type)
  305.         R1+12   window handle
  306.         R1+16   icon handle  
  307.  
  308. This call is used to update an icons border.  It is typically called as a result of a 
  309. Mouse_Click event, if the icon has a border type of 0 or 2 then the icon will slab 
  310. inwards.  The format of the validation string is described in the previous section.
  311.  
  312. The application should the perform the task and then force the icon to normal status 
  313. by calling Wimp_BorderIcon (SWI &81680) with R1+8 set to 0.
  314.  
  315. The code to border icons and windows is outlined in the section Programming 
  316. Interface. 
  317.  
  318. Note that the mouse coordinates specified in R1+0 and R1+4 are not used by the 
  319. SWI and are only present to make the block compatible with a Mouse_Click event 
  320. block.
  321.  
  322. Wimp_BorderWindow (SWI &81681)
  323.  
  324. None
  325.  
  326.  
  327.  
  328.  
  329.  
  330. Wimp_BorderWindow (Interface_Render3dWindow) (SWI &81681)
  331.  
  332. R1 = pointer to block
  333. R1 preserved
  334.  
  335. Interrupts are not defined
  336. Fast interrupts are enabled
  337.  
  338. Processor is in SVC mode
  339.  
  340. SWI is not re-entrant
  341.  
  342. The block contains the following on entry:
  343.  
  344.         R1+0    window handle
  345.         R1+4    visible area minimum x coordinate
  346.         R1+8    visible area minimum y coordinate
  347.         R1+12   visible area maximum x coordinate
  348.         R1+16   visible area maximum y coordinate
  349.         R1+20   scroll x offset relative to work area origin
  350.         R1+24   scroll y offset relative to work area origin
  351.         R1+28   current graphics window minimum x coordinate
  352.         R1+32   current graphics window minimum y coordinate
  353.         R1+36   current graphics window maximum x coordinate
  354.         R1+40   current graphics window maximum y coordinate
  355.  
  356. This call is used to redraw the borders of icons in the window that are not up-to-date,  
  357. this SWI is typically called during the redraw loop of a window.  The SWI will 
  358. update the window, drawing borders around any icons which have the b command 
  359. specified in the validation string and are within the specified graphics window.
  360.  
  361. The code to border icons and windows is outlined in the section Programming 
  362. Interface. 
  363.  
  364. Wimp_BorderIcon (SWI &81680)
  365.  
  366. None 
  367.  
  368.  
  369.  
  370.  
  371. Wimp_ClaimInterface (Interface_Initialise) (SWI &81682)
  372.  
  373. R0 = task handle
  374. R0 preserved
  375.  
  376. Interrupts are not defined
  377. Fast interrupts are enabled
  378.  
  379. Processor is in SVC mode
  380.  
  381. SWI is not re-entrant
  382.  
  383. This SWI allows your application to use pointers via the Interface module.  This 
  384. SWI should be called at the beginning of your program.  If you don't use 
  385. Wimp_ClaimInterface then your pointers will not be displayed.
  386.  
  387. Wimp_ReleaseInterface (SWI &81683)
  388.  
  389. None
  390.  
  391.  
  392.  
  393.  
  394. Wimp_ReleaseInterface (Interface_CloseDown) (SWI &81683)
  395.  
  396. R0 = task handle
  397. R0 preserved
  398.  
  399. Interrupts are not defined
  400. Fast interrupts are enabled
  401.  
  402. Processor is in SVC mode
  403.  
  404. SWI is not re-entrant
  405.  
  406. This SWI stops your application from using pointers.  When this SWI is called 
  407. Interface Manager will erase any workarea pointers assigned to your application and 
  408. free the memory.  This should be called in your exit handler, also if an error occurs 
  409. you should also call this SWI to stop other applications from gaining your pointers.
  410.  
  411. Wimp_ClaimInterface (SWI &81682)
  412.  
  413. None
  414.  
  415.  
  416.  
  417.  
  418. Wimp_SetWorkareaPointer (Interface_SetWorkareaPointer) (SWI &81684)
  419.  
  420. R1 = pointer to block
  421. R1 preserved
  422.  
  423. Interrupt status is undefined
  424. Fast interrupts are enabled
  425.  
  426. Processor is in SVC mode
  427.  
  428. SWI is not re-entrant
  429.  
  430. The block contains the following on entry:
  431.  
  432.         R1+0    window handle
  433.         R1+4    minimum x coordinate of bounding box
  434.         R1+8    minimum y coordinate of bounding box
  435.         R1+12   maximum x coordinate of bounding box
  436.         R1+16   maximum y coordinate of bounding box
  437.         R1+20   24 bytes of pointer data
  438.  
  439. This specifies the pointer for an area of the window.
  440. The bounding box coordinates are given relative to the window's work area origin.  
  441. R1+4 to R1+16 can be set to -1 to specify the whole of the window's work area.
  442. The pointer data at +20 to +44 contains the sprite name and any x, y offset, see 
  443. validation strings for more information.
  444.  
  445. Wimp_RemoveWorkareaPointer (SWI &81685)
  446. Wimp_PollPointer (SWI &81686)
  447.  
  448. None
  449.  
  450.  
  451.  
  452.  
  453.  
  454. Wimp_RemoveWorkareaPointer (Interface_RemoveWorkareaPointer) (SWI &81685)
  455.  
  456. R0 = task handle
  457. R1 = pointer to block
  458.  
  459. R0 preserved
  460. R1 preserved
  461.  
  462. Interrupt status is undefined
  463. Fast interrupts are enabled
  464.  
  465. Processor is in SVC mode
  466.  
  467. SWI is not re-entrant
  468.  
  469. The block contains the following on entry:
  470.  
  471.         R1+0    window handle
  472.         R1+4    minimum x coordinate of bounding box
  473.         R1+8    minimum y coordinate of bounding box
  474.         R1+12   maximum x coordinate of bounding box
  475.         R1+16   maximum y coordinate of bounding box
  476.  
  477. This call removes a previously installed pointer from the list of active pointer areas 
  478. for the specified window.  When a window is deleted you should remove any 
  479. pointers that were related to the window, otherwise these pointers may become 
  480. active on any window which gains the same window handle in the future. 
  481.  
  482. The bounding box coordinates are given relative to the window's work area origin.  
  483. R1+4 to R1+16 can be set to -1 to specify the whole of the window's work area.  
  484. R1+4 to R1+16 may be set to 0 to remove all work area pointers assigned to the 
  485. window.
  486.  
  487. Wimp_SetWorkareaPointer (SWI &81684)
  488. Wimp_PollPointer (SWI &81686)
  489.  
  490. None
  491.  
  492.  
  493.  
  494.  
  495.  
  496. Wimp_PollPointer (Interface_Poll) (SWI &81686)
  497.  
  498. R0 = Wimp_Poll reason code
  499. R2 = task handle
  500.  
  501. R0 preserved
  502. R@ preserved
  503.  
  504. Interrupt status is undefined
  505. Fast interrupts are enabled
  506.  
  507. Processor is in SVC mode
  508.  
  509. SWI not re-entrant
  510.  
  511. This call checks to see if the pointer is up-to-date.  If the pointer is not up-to-date it 
  512. will change to the pointer specified in the icons validation string.  If the pointer is 
  513. not over an icon then  the pointer will change according to the position on the 
  514. window background.
  515.  
  516. Note that wimp_poll reason codes 0 and 4 should not be masked out, otherwise the 
  517. pointer will be out-of-date and will not function correctly.
  518.  
  519. Wimp_SetWorkareaPointer (SWI &81684)
  520. Wimp_RemoveWorkareaPointer (SWI &81685)
  521.  
  522. None
  523.  
  524.  
  525.  
  526.  
  527.  
  528. Wimp_SendInformation (Interface_SendHelp) (SWI &81687)
  529.  
  530. R1 = message block as returned from help application
  531. R1 preserved
  532.  
  533. Interrupt status is undefined
  534. Fast interrupts are enabled
  535.  
  536. Processor is in SVC mode
  537.  
  538. SWI not re-entrant
  539.  
  540. This call returns a help text message to the interactive help application.  It should be 
  541. called when a message with the number &502 is received and the pointer is over an 
  542. icon.  If there is a message in the icons validation string that the pointer is currently 
  543. over then this will be sent to the help application.  It is up to the applications 
  544. programmer to take care of the help message when the pointer is over the icon on the 
  545. icon bar or is over the window workarea. 
  546.  
  547. None
  548.  
  549. None
  550.  
  551.  
  552. Wimp_PreProcessKey (Interface_PreProcessKey) (SWI &81688)
  553.  
  554. R0 = event type
  555. R1 = event block
  556. R2 = task handle
  557.  
  558. R0 = updated to new event type
  559. R1 = updated event block
  560. R2 = 0 if event was not dealt intercepted
  561.  
  562. This call pre-processes the up, down, tab, shift-tab keys and any specified in a specific icons
  563. validation string using the command k<keycode>.  The SWI will move icon, if neccessary or activate
  564. a button.  This call sould be called after the wimp_poll command, it will match the key to an icon
  565. and if neccessary modify your wimp poll block and event type.
  566.  
  567.  
  568. Wimp_BorderPlotIcon (Interface_Plot3dIcon) (SWI &81689)
  569.  
  570. R0 = window state (either from wimp_update/redraw or from a wimp_getwindowstate)
  571. R1 = icon block as for Wimp_PlotIcon
  572.  
  573. This call plots a border on a window like Wimp_PlotIcon.  The icon block passed in R1
  574. should contain a block as described for Wimp_PlotIcon in the PRMs.
  575.  
  576. Wimp_BorderBoundingBox (Interface_BoundingBox) (SWI &8168A)
  577.  
  578. R1 = icon block as for Wimp_PlotIcon
  579.  
  580. R1 = updates icon block
  581.           
  582.           offset
  583.           0         min x
  584.           4         min y
  585.           8         max x
  586.           12        max y
  587.           16        border width
  588.           20        button slab state (1 = out, 0 = in)
  589.  
  590. This call returns information about the icon block passed to it.  If you wish to
  591. get the size of an icons box use Wimp_GetIconState and then pass the icon block 
  592. returned to this function.
  593.  
  594.  
  595.  
  596. Changes from version 1.32
  597.  
  598. this version has been fully re-written using the acorn aof assembler.
  599. border type has changed to z to avoid conflicts with risc-os 3
  600. Interface_Plot3dIcon has been changed so the first parameter is a window state block instead of a window handle
  601. names has changed to interface_...., old names are still supported
  602. better redraw code to correct problems with multi-sync modes where the icons were not alligned correctly.
  603. Interface_BoundingBox now returns the state of the button 
  604. new border types
  605.  
  606. *command to allow changes in the slabbing colours.