Source code for DeleteGuard
===========================

The DeleteGuard module contains a filter which intercepts calls made to the
filer from Wimp_Poll with reason code 9 (menu selection). The filter checks
for the main menu and submenu item numbers corresponding to the 'Delete'
option. If these are found, an error box is generated with 'OK' and 'Cancel'
buttons and the message 'Are you sure you want to delete the chosen
object(s)?'. If the 'Cancel' box is clicked or Escape is pressed, the call
from Wimp_Poll is not passed on to the filer so that deletion does not
happen.

The main menu and submenu item numbers are set near the start of the source
code as BASIC variables menu_item% and submenu_item%. These are set as 1 and
2 respectively, counting from zero from the top of the menu. If the 'Delete'
option is in a different position in a future version of RISC OS, these
variables may easily be changed and the code recompiled.

The module detects a delete command by intercepting the menu selection in
preference to looking for a filing system delete command so that, if several
files are being deleted, the user is not prompted for confirmation several
times, which could be annoying. It is not possible to check for the word
'Delete' in the menu item as this would require the address of the filer
menu block which is not available.

Module header
=============

The only active entries in the module header are the initialisation and
finalisation code and the addresses of the title and help strings.

Initialisation code
===================

The module first calls OS_Byte 129,0,255 to get the OS version number and
refuses to initialise if it is earlier than RISC OS 3.

A 16-byte data buffer is created on the stack and information obtained from
the task manager on each task in turn until the filer is found. As the filer
task handle is the only data that needs to be stored, the module does not
claim any workspace but stores the task handle in its private word, pointed
to by R12.

The DelG filter is registered as a Wimp post-filter. As the register setup
is the same for registration and deregistration, a subroutine common to both
is used. The filter is set to filter only the filer input and only Wimp_Poll
reason code 9.

Finalisation code
=================

When the module is shut down, the finalisation code simply deregisters the
filter, using the same data as registration.

DeleteGuard filter code
=======================

Although the filter should only be called with a Wimp_Poll reason code of 9,
the reason code is checked in case the unexpected happens, possibly due to a
combination of filters being active.

When Wimp_Poll returns with reason code 9, R1+0 contains the main menu item
number and R1+4 the first submenu item number. These are checked against the
values set in menu_item% and submenu_item% and the call passed on to the
filer if a different selection has been made, otherwise an error box is
generated with 'OK' and 'Cancel' boxes. If 'Cancel' is selected, or the
Escape key pressed, R0 is set to -1 before the filter exits, which prevents
the call from being passed on to the filer, thus preventing the selected
object(s) from being deleted.

Martyn Fox