The Datafile PD-CD 5/DATAFILE_PDCD5.iso/utilities/i/iclear/ReadMe

Text File | 1996-10-13 | 8KB | 148 lines

                               IClear Module
                               ====== ======

                               by Martyn Fox

This software is Public Domain. It may be freely copied and distributed,
including distribution by magazine discs, PD libraries, bulletin boards
etc., provided the following conditions are adhered to:

1. No charge is made other than to cover the reasonable cost of duplication
and distribution.

2. No alteration is made to either the software or this text file.

3. This text file accompanies all copies of the software.

Please note that this module will only work with RISC OS 3 or later. This
copy has been modified for compatibility with the StrongARM 110 processor.

IClear is a module which makes it easier to delete text from a writable
icon. Under RISC OS, to replace the text in such an icon with new text, you
first have to either delete all the characters of the old text or press
Ctrl-U to clear it. This can be a nuisance, especially if you have just
selected the icon with the mouse, as you first have to transfer to the
keyboard, then press Ctrl-U before you can type in your new text.

With IClear running, simply double-click on the writable icon, using either
Select or Adjust. The icon will be inverted, which usually means that it
will turn black with white text. As soon as you press a key, the text in the
icon will vanish, to be replaced with the character that you typed. If you
change your mind after inverting the icon and decide you want to keep your
existing text, a further click with any mouse button anywhere on the screen
will de-invert the icon and put things back to normal.

This software will work with writable icons (button type 15) and also
draggable writable icons (button type 14) but not with writable menu items.

                             Programming Notes
                             =========== =====

The module intercepts the MouseV and InsV vectors to detect calls to
OS_Mouse and keypresses. OS_Mouse calls are first passed onto the SWI
routine and processed on exit.

Because RISC OS will not automatically detect a double-click over a writable
icon, the module has to do the job itself. This involves checking the time
interval since the previous click, selecting the 'double-arrow' pointer
sprite, checking which button was pressed and monitoring the mouse position.

Rather than put too much code into a vector intercept routine, the software
just sets one of two callbacks, depending on the time interval since the
previous click. The callback routine is called by RISC OS as soon as it is
not busy. The first of these callbacks handles a single click. It first
checks to see if the module has a record of an inverted icon and, if so,
takes steps to clear it. It then stores a record of which button was pressed
and checks the icon type. If the click was over a writable icon, it stores
the mouse position and redefines mouse pointer 1 sprite as ptr_double.

N.B. There appears to be no way of reading which sprite is used by a
particular pointer number. Versions of this module up to v1.01 always
replaced the double pointer with the ptr_default sprite after the
double-click time-out. Subsequent versions checks the icon’s validation
string, if any, looking for the ‘P’ instruction, which sets an alternative
pointer sprite when over the icon, and restore the pointer to this sprite
after first checking its presence in the Wimp sprite pool.

The module then sets a call-after, which is an instruction to RISC OS to
call a routine after a certain length of time. It also calls OS_CallEvery to
arrange for a call every 10 centiseconds to a routine which checks the mouse
position and cancels the double-click monitoring if the mouse is moved more
than a certain amount.

N.B. Although the normal double-click time limit and permitted mouse
movement can be configured, there appears to be no way of reading their
values, other than the unreliable method of checking CMOS RAM locations,
which could change between different versions of RISC OS. This module uses
the default configuration values of 1 second maximum between clicks and a
maximum mouse movement of 10 OS units (it checks for either 10 horizontal or
10 vertical units of movement). These values are fixed in this version of
the module. If there is a demand for the ability to alter these values, I
will endeavour to include a couple of SWIs and/or star commands in a later
version.

If either a second button is pressed or the mouse is moved before the
call-after has timed out, the call-after and call-every are cancelled and a
second callback is used. This routine checks that the same button has been
pressed as previously, sets a flag and takes steps to invert the icon.

Although any icon can be inverted or de-inverted by means of a call to
Wimp_SetIconState, the procedure is not that simple. This SWI may only be
called while the application which owns the icon is the currently active
task. If we simply call it when the mouse is clicked, this may not be the
case, especially if several multi-tasking applications are running at the
same time. We have to send a message to the task but we cannot, of course,
rewrite its software.

The solution is to use a filter. We could use a pre-filter, which is called
just before Wimp_Poll is executed, or a post-filter which is called on
return from Wimp_Poll. In this case, we use the latter. The technique is to
send a unique message to the task which our filter will intercept and
recognise, telling it to invert or de-invert the required icon. Version
v1.10 also uses the filter to check the icon’s validation string to get the
pointer sprite name.

We could send a message, using reason code 17 or 18, but we would have to
find a message action code that is not used for anything else, which would
present problems. It is also permissible for a task to mask out these reason
codes, which would prevent our message getting through. So that this cannot
happen, the module sends a message with reason code 2, which usually means
'open window request'. This reason code is not supposed to be masked out
when calling Wimp_Poll. Our message sends R1+0 as zero and R1+4 as
&726C4349, which is the ASCII code for 'IClr'. This corresponds to a request
to open the window whose handle is zero, with a minimum x coordinate of
&726C4349 - a most unlikely state of affairs in any other situation! The
third word in the block contains the action code for the call. Bit 1 set
denotes that the call is to invert or clear the icon - bit 0 is cleared to
clear, set to invert. Bit 2 is set to call the routine to read the
validation string.

If a key is pressed while the inverted icon flag is set, the routine (again
by means of a callback) sends a message to clear the icon, then sends the
keypress character, preceded by a Ctrl-U to delete the text.

The module incorporates a self-checking routine to detect corruption by
viruses.

StrongARM compatibility

The Engineering Support Application Note distributed by Acorn with the
StrongARM processor states that storing the program counter to memory stores
PC+8 instead of PC+12, as in the case of the ARM, and points out that the
example code on page 1-107 of the PRM will not work for this reason.
Unfortunately, this code had been used by versions of IClear up to v1.10,
with the result that loading the module caused the machine to crash. A
simple modification to a few lines of code has restored compatibility while
maintaining backward compatibility with earlier ARM processors.

Incidentally, use of this module revealed that the configuration dialogue
box of software PC Emulator v1.70 contained a writable icon which was
created in its inverted state. Its response to a double-click is to remain
black-on-white. A subsequent single click clears it to white-on-black!

Please send all comments and suggestions to:

M.P. Fox,
31 Pierson Road,
Windsor,
Berks. SL4 5RE