home *** CD-ROM | disk | FTP | other *** search
/ APDL Public Domain 1 / APDL_PD1A.iso / deskutils / _a_l / iclear / Help next >
Encoding:
Text File  |  1993-07-12  |  6.6 KB  |  128 lines
  1.                                IClear Module
  2.                                ====== ======
  3.  
  4.                                by Martyn Fox
  5.  
  6. This software is Public Domain. It may be freely copied and distributed,
  7. including distribution by magazine discs, PD libraries, bulletin boards
  8. etc., provided the following conditions are adhered to:
  9.  
  10. 1. No charge is made other than to cover the reasonable cost of duplication
  11. and distribution.
  12.  
  13. 2. No alteration is made to either the software or this text file.
  14.  
  15. 3. This text file accompanies all copies of the software.
  16.  
  17. Please note that this module will only work with RISC OS 3 or later.
  18.  
  19. IClear is a module which makes it easier to delete text from a writable
  20. icon. Under RISC OS, to replace the text in such an icon with new text, you
  21. first have to either delete all the characters of the old text or press
  22. Ctrl-U to clear it. This can be a nuisance, especially if you have just
  23. selected the icon with the mouse, as you first have to transfer to the
  24. keyboard, then press Ctrl-U before you can type in your new text.
  25.  
  26. With IClear running, simply double-click on the writable icon, using either
  27. Select or Adjust. The icon will be inverted, which usually means that it
  28. will turn black with white text. As soon as you press a key, the text in the
  29. icon will vanish, to be replaced with the character that you typed. If you
  30. change your mind after inverting the icon and decide you want to keep your
  31. existing text, a further click with any mouse button anywhere on the screen
  32. will de-invert the icon and put things back to normal.
  33.  
  34. This software will work with writable icons (button type 15) and also
  35. draggable writable icons (button type 14) but not with writable menu items.
  36.  
  37.                              Programming Notes
  38.                              =========== =====
  39.  
  40. The module intercepts the MouseV and InsV vectors to detect calls to
  41. OS_Mouse and keypresses. OS_Mouse calls are first passed onto the SWI
  42. routine and processed on exit.
  43.  
  44. Because RISC OS will not automatically detect a double-click over a writable
  45. icon, the module has to do the job itself. This involves checking the time
  46. interval since the previous click, selecting the 'double-arrow' pointer
  47. sprite, checking which button was pressed and monitoring the mouse position.
  48.  
  49. Rather than put too much code into a vector intercept routine, the software
  50. just sets one of two callbacks, depending on the time interval since the
  51. previous click. The callback routine is called by RISC OS as soon as it is
  52. not busy. The first of these callbacks handles a single click. It first
  53. checks to see if the module has a record of an inverted icon and, if so,
  54. takes steps to clear it. It then stores a record of which button was pressed
  55. and checks the icon type. If the click was over a writable icon, it stores
  56. the mouse position and redefines mouse pointer 1 sprite as ptr_double.
  57.  
  58. N.B. There appears to be no way of reading which sprite is used by a
  59. particular pointer number. The PRM though says that only RISC OS should use
  60. pointer 1, so this pointer should presumably always use the ptr_default
  61. arrow sprite. The module assumes this and always replaces ptr_double with
  62. ptr_default at the end of the period during which it checks for a second
  63. click.
  64.  
  65. The module then sets a call-after, which is an instruction to RISC OS to
  66. call a routine after a certain length of time. It also calls OS_CallEvery to
  67. arrange for a call every 10 centiseconds to a routine which checks the mouse
  68. position and cancels the double-click monitoring if the mouse is moved more
  69. than a certain amount.
  70.  
  71. N.B. Although the normal double-click time limit and permitted mouse
  72. movement can be configured, there appears to be no way of reading their
  73. values, other than the unreliable method of checking CMOS RAM locations,
  74. which could change between different versions of RISC OS. This module uses
  75. the default configuration values of 1 second maximum between clicks and a
  76. maximum mouse movement of 10 OS units (it checks for either 10 horizontal or
  77. 10 vertical units of movement). These values are fixed in this version of
  78. the module. If there is a demand for the ability to alter these values, I
  79. will endeavour to include a couple of SWIs and/or star commands in a later
  80. version.
  81.  
  82. If either a second key is pressed or the mouse is moved before the
  83. call-after has timed out, the call-after and call-every are cancelled and a
  84. second callback is used. This routine checks that the same key has been
  85. pressed as previously, sets a flag and takes steps to invert the icon.
  86.  
  87. Although any icon can be inverted or de-inverted by means of a call to
  88. Wimp_SetIconState, the procedure is not that simple. This SWI may only be
  89. called while the application which owns the icon is the currently active
  90. task. If we simply call it when the mouse is clicked, this may not be the
  91. case, especially if several multi-tasking applications are running at the
  92. same time. We have to send a message to the task but we cannot, of course,
  93. rewrite its software.
  94.  
  95. The solution is to use a filter. We could use a pre-filter, which is called
  96. just before Wimp_Poll is executed, or a post-filter which is called on
  97. return from Wimp_Poll. In this case, we use the latter. The technique is to
  98. send a unique message to the task which our filter will intercept and
  99. recognise, telling it to invert or de-invert the required icon.
  100.  
  101. We could send a message, using reason code 17 or 18, but we would have to
  102. find a message action code that is not used for anything else, which would
  103. present problems. It is also permissible for a task to mask out these reason
  104. codes, which would prevent our message getting through. So that this cannot
  105. happen, the module sends a message with reason code 2, which usually means
  106. 'open window request'. This reason code is not supposed to be masked out
  107. when calling Wimp_Poll. Our message sends R1+0 as zero and R1+4 as
  108. &726C4349, which is the ASCII code for 'IClr'. This corresponds to a request
  109. to open the window whose handle is zero, with a minimum x coordinate of
  110. &726C4349 - a most unlikely state of affairs in any other situation! The
  111. third word in the block is zero to clear the icon or 1 to invert it. The
  112. filter is set to handle only reason code 2. If it receives the exact state
  113. of affairs as described, it either inverts or clears the icon and exits
  114. without passing the call onto the application.
  115.  
  116. If a key is pressed while the inverted icon flag is set, the routine (again
  117. by means of a callback) sends a message to clear the icon, then sends the
  118. keypress character, preceded by a Ctrl-U to delete the text.
  119.  
  120. The module incorporates a self-checking routine to detect corruption by
  121. viruses.
  122.  
  123. Please send all comments and suggestions to:
  124.  
  125. M.P. Fox,
  126. 31 Pierson Road,
  127. Windsor,
  128. Berks. SL4 5RE