/----------------------------\
|        ScreenGrabber       |
|  Christopher Bazley, 2000 |
|     Screenshot grabber     |
| Version 2.26 (04 Mar 2012) |
\----------------------------/
N.B. This text is best viewed at a display width of 77 columns.

Introduction
============

  ScreenGrabber is a relocatable module that allows you to take pictures of
the screen display by pressing a 'hot' key or executing the star command
*SGrab. Each picture is saved as a separate Sprite file, optionally including
the current palette.

  ScreenGrabber was originally designed for taking screenshots of single-
tasking programs such as games and graphical demos. For that reason it does
not integrate particularly well with the desktop environment. (It monitors
low-level key transitions instead of intercepting Wimp key press events and
therefore pressing its hot key may have side-effects, if that key is also
used by a desktop application.)

  However, I have supplied a desktop front-end to make it easier to configure
the back-end module. Most users will be able to use this front-end without
ever needing to investigate the star commands provided by the module.

Requirements
============

  To run the ScreenGrabber module you need RISC OS 3.10 or newer. To run the
desktop front-end, you also need the relevant Toolbox modules (Toolbox,
Window, ProgInfo, Menu, Iconbar and SaveAs) in ROM or installed in your
!System application.

  For genuine RISC OS 3.10 users (are there any?), you also need all the
ThreeTen support stuff in !System, which you undoubtedly already have by now.

  To save choices from the front-end application, the system variable
Choices$Write must have been set up. This variable is set automatically when
most modern RISC OS machines boot up. RISC OS 3.1 users who don't want to
install Acorn's universal !Boot application [1] can alternatively use the
stand-alone !Choices application distributed with !Printers 1.64a [2].

1: http://acorn.riscos.com/riscos/releases/UniBoot/uniboot.zip
2: http://support.riscos.com/Support/Releases/Printers/Printers164a.zip

Quick Guide
===========

  Double-click on the !ScGrabber icon in a directory display to load the
front-end application, which will in turn load the ScreenGrabber module.

  Click SELECT on the ScGrabber icon that should have appeared on the
iconbar (a camera on a green background). This will open a Choices dialogue
box to allow you to configure ScreenGrabber.

  Drag the Sprite file icon from the 'Saving files' section of the Choices
dialogue box to a directory display where you want screenshots to be
saved. The adjacent writable field should be automatically updated so that
the file name includes the full path of the chosen directory.

  Click SELECT on the 'Set' button to reconfigure the ScreenGrabber module
and close the dialogue box.

  Press the 'Print' key on your keyboard (next to the 'Scroll Lock' key, it
may be labelled 'Prt Sc', 'Print Scrn' or similar). A Sprite file called
"SGrab00000" should appear in your chosen directory. Press this key again
and a file named "SGrab00001" should appear.

  For further details, read on.

Keyboard controls
=================

  If ScreenGrabber is enabled then pressing its configured hot key (default:
'Print') will save a screenshot. To take a continuous stream of screenshots,
simply hold the key down and release it when you want to stop recording. The
frequency with which screenshots are saved depends upon the configured
recording rate. When you have finished recording, you can convert the numbered
screenshots into an animated GIF by using Peter Hartley's InterGif program:
http://utter.chaos.org.uk/~pdh/software/intergif.htm

  Often, you will want to have both hands free whilst recording an animation -
especially if you are playing a fast-moving game. In such circumstances, you
can 'lock' ScreenGrabber so that it continues recording even after the hot key
has been released. This mode can be activated by holding down Ctrl when
pressing the hot key. To 'unlock' ScreenGrabber, press the hot key again but
without holding Ctrl - recording will stop when the hot key is released.

  The effect of the Ctrl key modifier can be reversed by a configuration
option (see 'Choices dialogue box' for details). In summary:

In '*SGrabFilm off' mode
  Press hot key: start filming and 'unlock'
  Hold Ctrl and press hot key: start filming and 'lock'
  Release hot key: stop filming unless 'locked'

In '*SGrabFilm on' mode
  Press hot key: start filming and 'lock'
  Hold Ctrl and press hot key: start filming and 'unlock'
  Release hot key: stop filming unless 'locked'

  Be careful not to accidentally leave ScreenGrabber recording or you could
easily waste megabytes of storage space. Continuous recording is strenuous, so
the computer will slow down a lot. You can reduce the load by increasing the
interval between screenshots. The default is 10 centiseconds but increasing
this would only cause a minor degradation in the smoothness of animations
recreated from the screenshots.

Iconbar menu
============

  The menu which appears when you click MENU on the ScGrabber icon on the
iconbar gives access to all the facilities provided by the desktop front-end:

  'Info' leads to a standard 'About this program' dialogue box, which provides
information about the front-end application. Note that the displayed version
number and date may differ from that of the back-end module.

  Clicking on 'Help...' will open this user manual.

  Clicking on 'Choices...' will open a dialogue box to allow you to
reconfigure the back-end module (the same as clicking SELECT on the iconbar
icon).

  'Save script' leads to a dialogue box which allows you to save the current
configuration as a set of star commands in an Obey file.

  Clicking on 'Reset counter' will zero a monotonic counter that is used to
generate a unique file name for each screenshot. Subsequently, any screen
shots already saved will be overwritten by more recent ones.

Choices dialogue box
====================

  Changes to settings in the Choices dialogue box will not take effect until
you click on the 'Set' button (or press Return), and may be undone at any time
by clicking on the 'Cancel' button (or pressing Escape). The 'Save' button
acts like 'Set' except that the displayed settings will be saved so that they
are retained if the front-end is quit and then reloaded.

  The 'Hot key' group of controls allow you to configure which key will
activate ScreenGrabber and how it should respond to key presses. You may
find it useful to disable the hot key when you are not using ScreenGrabber,
to avoid accidentally grabbing screenshots whilst using desktop applications.

  Switch on the 'Record until stopped' option to reverse the usual effect of
the Ctrl key modifier so that ScreenGrabber continues recording after the hot
key has been released unless Ctrl was held when it was pressed. In this mode,
recording can be cancelled by holding Ctrl whilst pressing and releasing the
hot key again.

  Which key is ScreenGrabber's hot key may be specified either as an internal
key code or by name. You can enter a number in the writable field using the
keyboard, or click on the adjacent arrows to adjust the key code up or down in
steps of one (the name shown in the neighbouring display field will be updated
in parallel). Alternatively, click on the pop-up menu button to select from a
list of key names, and the corresponding key code will be filled out.

  If your computer is configured to use a keyboard for a country other than
the UK then the display field and pop-up menu button adjacent to the key code
will be faded. The front-end is supplied with only one mapping between
internal key codes and names, for the UK. If you want to teach it key names
for a different country then you must create a file within the application,
named after the country number (e.g. !ScGrabber.Keyboards.6 would contain the
key mapping for France). You can find the country number by executing the
following snippet of BASIC: SYS 6,70,127 TO ,c%:PRINT c%

  The 'Saving files' group of controls allow you to configure where screen
shots should be saved by ScreenGrabber, and some details of the Sprite file
format to be used.

  To set the location to save screenshots you can type a file path into the
writable field, or drag the Sprite file icon to a directory display. If you
specify only a 'leaf' file name then screenshots will be saved relative to
the work directory. It is unwise to specify a partial file path because it
will probably become invalid if a different work directory is selected (sub-
directories are not automatically created by ScreenGrabber).

  A five digit numeric suffix will be appended to the file path when saving
screenshots. This suffix will be padded with leading zeros so that the
Filer's 'Sort by name' option displays the files in the correct order. Many
older filing systems have a ten character limit on filenames (e.g. ADFS 'E'
or 'F' format discs); in such cases you must make sure that the 'leaf' part of
the file path is no more than five characters long.

   Changing the filename has the side-effect of resetting the screenshot
counter to 0.

  Switch on the 'Save palette' option to include the current palette when
saving screenshots. This increases the size of each Sprite file by up to 2 KB
but but ensures that colours are reproduced accurately. If you know that the
default palette is being used then you can switch it off.

  Switch on the 'New sprite type' option to encode the colour depth and dot
density of a sprite using a new-style type specifier (supported from RISC OS
3.5 onwards) in preference to an old-style mode number. By default this option
is switched off, for backward compatibility. A type specifier will be used for
sprite formats which cannot be represented by a mode number, regardless of the
configured preference.

  The 'Recording rate' group of controls allow you to control how often
ScreenGrabber should save a screenshot whilst the hot key is held down (akin
to 'auto repeat' of characters when entering text). The first screenshot
is always saved immediately when the key is pressed.

  Switch on the 'Auto synchronise' option to save another screenshot whenever
ScreenGrabber detects that a different screen bank is displayed. This is
useful to record output from programs that use a back buffer for smooth
animation.

  Switch on the 'Half speed' option to save another screenshot ever second
time that a different screen bank is displayed (i.e record alternate frames).
This is a less processor-intensive method of recording output from programs
which maintain a high frame rate.

  Switch on the 'Fixed interval' option to wait for a fixed period between
saving each screenshot and the next one. This is the only practical way of
recording output from programs that don't use a back buffer at all. The
minimum interval allowed is 2 centiseconds between frames.

Saving a script
===============

  The front-end application can write out its current settings as an Obey
file of star commands, which can then be run independently to reconfigure
the ScreenGrabber module. You can access this facility from the iconbar menu
('Save script' leads to a standard savebox).

  The default save location is "<Choices$Write>.Boot.Tasks.SGrabSetup", which
will ensure that the ScreenGrabber module is loaded and configured as part
of your boot sequence. If you choose to save the Obey file here then you
must ensure that environment variable ScGrabber$Dir is set earlier in your
boot sequence; otherwise you will get an error 'Can't find the !ScGrabber
application' upon booting your machine.

  On RISC OS 4 the solution is to add !ScGrabber to the list of applications
to 'Boot at startup'. (Double-click your !Boot application to run Configure,
select the 'Boot' plug-in, 'Look at' and then drag the ScGrabber icon to the
scrolling list.) This works because files in Choices:Boot.Tasks are run only
after any applications specified by the user have been run, booted or added
to the iconbar 'Apps' folder.

Star Commands
=============

  The following additional star commands become available when the
ScreenGrabber module is loaded. They provide access to the same features
that are reflected by the desktop front-end, which allows the module to be
used stand-alone outside the desktop environment. Because the front-end is
unaware of the internal configuration of the module, mixing command line
usage with desktop usage isn't recommended.

*SGrab [<file path>]
  Saves the current screen display as a Sprite file. If no file path is
  supplied then the default will be used.

*SGrabHotKey [On|Off|<key name>|!<key number>]
  Allows the key that triggers screenshots to be enabled, disabled,
  reassigned, or shows the current setting if no argument is passed. You can
  specify a key by name or internal code. In the latter case the number
  should be preceded by an exclamation mark:

  !0  Escape      !25 9          !50 ]         !75 Keypad+  !100 Right
  !1  F1          !26 0          !51 #         !76 LShift   !101 Keypad0
  !2  F2          !27 -          !52 Delete    !77 \        !102 Keypad.
  !3  F3          !28 =          !53 End       !78 Z        !103 Enter
  !4  F4          !29           !54 PageDown  !79 X
  !5  F5          !30 Backspace  !55 Keypad7   !80 C
  !6  F6          !31 Insert     !56 Keypad8   !81 V
  !7  F7          !32 Home       !57 Keypad9   !82 B
  !8  F8          !33 PageUp     !58 Keypad-   !83 N
  !9  F9          !34 NumLock    !59 LCtrl     !84 M
  !10 F10         !35 Keypad/    !60 A         !85 ,
  !11 F11         !36 Keypad*    !61 S         !86 .
  !12 F12         !37 Keypad#    !62 D         !87 /
  !13 Print       !38 Tab        !63 F         !88 RShift
  !14 ScrollLock  !39 Q          !64 G         !89 Up
  !15 Break       !40 W          !65 H         !90 Keypad1
  !16 `           !41 E          !66 J         !91 Keypad2
  !17 1           !42 R          !67 K         !92 Keypad3
  !18 2           !43 T          !68 L         !93 CapsLock
  !19 3           !44 Y          !69 ;         !94 LAlt
  !20 4           !45 U          !70 '         !95 Space
  !21 5           !46 I          !71 Return    !96 RAlt
  !22 6           !47 O          !72 Keypad4   !97 RCtrl
  !23 7           !48 P          !73 Keypad5   !98 Left
  !24 8           !49 [          !74 Keypad6   !99 Down

  Before version 2.15 of the ScreenGrabber module, the key which generates
  internal code 16 was named ~ (tilde) instead of ` (grave accent). I renamed
  it for consistency with the other key names, which refer to the Risc PC
  rather than Archimedes keyboard layout. The old name is still recognised
  for backward compatibility.

*SGrabPalette [on|off]
  Controls whether the current palette is saved with screenshots, or shows
  the current setting if no argument is passed.

*SGrabResetCount
  Resets the counter that is used as a file name postfix when saving
  screenshots.

*SGrabFilename [<filename>]
  Sets the base file path (without postfix) to which screenshots should be
  saved, or shows the current file path if no argument is passed. Changing
  the file path will also reset the screenshot counter.

*SGrabFilm [on|off]
  Controls whether the default action is to continue recording when the hot
  key is released, or shows the current setting if no argument is passed.

*SGrabFilmDelay [<delay time>|auto|half]
  Controls the interval (in centiseconds) between recording each screenshot.
  'Auto' will take a screenshot whenever a different bank is displayed,
  whereas 'Half' records every other frame. If no argument is passed then the
  current setting is shown.

*SGrabStatus
  Displays the current status of the ScreenGrabber module, including any OS
  error that happened in the background since the last invocation of this
  command.

*SGrabConfigure [-On|-Off] [-Single|-Film]
                [-KeyName <key name>|-KeyCode <key code>]
                [-Interval <centiseconds>|-AutoSync|-HalfSync]
                [-[No]Palette] [-NewSprite|-OldSprite] [-Filename <filename>]

  Configures the ScreenGrabber module. Any options not specified will be left
  in their current state. It is equivalent to using a combination of
  *SGrabHotKey, *SGrabFilm, *SGrabFilmDelay, *SGrabPalette and *SGrabFilename
  but can also be used to configure a preference for encoding the colour
  depth and dot density of sprites using an old-style mode number or new-
  style type specifier.

Limitations
===========

  Grabbing the screen palette with the picture will not work correctly with
games that program the palette directly rather than through RISC OS.

  You can only save up to 100,000 files with the same base filename. After
that, the numeric suffix will wrap around from 99999 to 00000. This equates
to 2 hours and 40 minutes of film at the default rate of 10 frames per
second, or 8 gigabytes of screenshots at a resolution of 320 x 256 and
colour depth of 8 bpp!

  It is unwise to attempt to record at a frame rate which is too high. The
shortest interval that can be configured is 2 centiseconds, but your computer
is unlikely to be able to create 50 files per second. Even at a relatively
low pixel resolution and colour depth such as that cited above, this frame
rate would require a data transfer rate of 32.79 Mbit/s! My StrongARM Risc PC
could only manage 3679.81 kbit/s - between 5 and 6 FPS - in a recent test
of saving screenshots of that format to its hard disc (using the on-board
IDE controller).

  The screenshot timing mechanism runs on interrupts for accuracy and to
avoid busy waiting, whereas screenshots can only be saved when RISC OS is
idling or being threaded out of. The interrupt routine will only add a
transient callback to save a screenshot if the preceding screenshot has
already been completed. This avoids a glut of overdue screenshots if
the configured interval is too short or there is a long delay before the
system returns to USR mode with interrupts enabled.

  If there is a significant time lag in servicing transient callbacks then
the 'auto synchronise' feature may not catch every display bank swap.

  The key names recognised by *SGrabHotKey are hard-wired for a standard UK
keyboard (which is unhelpful for those using a foreign keyboard layout).

History
=======

1.00 (10th December 2000)
 - Initial release. Had serious problems with half-drawn/corrupted pictures
   in Star Fighter 3000.

1.10 (1st March 2001)
 - Now saves the bank displayed rather than the one being written to - it
   simply never occured to me that *ScreenSave would be soooo STUPID!
 - Also, ScreenGrabber now cleverly protects against interrupt-driven
   screenbank swapping during the screenshot.

N.B. Version number is the application version number (from 'about' window),
which is not necessarily the same as the module version number.

2.00 (14th March 2001)
 - Module rewritten in C as an exercise, using Acorn CC and CMHG.
 - Supposedly 32-bit compatible (untested since we have no 32-bit OS yet!)
 - Added a Wimp front-end to aid configuration of the module.
 - Lots of new CLI commands. All of them, in fact.
 - Can now make 'films' of variable speed, if you have disc space to burn.
 - Will optionally synchronise film with screenbank swaps.
 - Command to disable hotkey without RMKill-ing the module.
 - Screen shot counter can be reset without RMReinit-ing the module.
 - The screenshots base filename is now configurable.

2.01 (17th March 2001)
 - Amended !Run file to give sensible sized WimpSlot for front-end.
 - Now ensures that the relevant Toolbox modules are loaded.
 - Relevant Toolbox modules supplied with distribution.

2.02 (29th March 2001)
 - Knocked about 2k off the size of the module by removing lots of unused
   functions which had accidentally been compiled in!
 - Changed the help messages to use CMHG 5.10-style invalid-syntax strings.

2.03 (5th July 2001)
 - Setup dbox is more proficient at regaining the input-focus.
 - New key short-cut 'f1' opens manual.
 - Much tidying up to make front-end source recompilable.
 - Cosmetic improvement to error reporting.
 - Made provision for inclusion of internationalised resources (for front-
   end, not module).

2.04 (5th June 2002)
 - General fiddling and recompilation. !RunImage now distributed in squeezed
   form. Module seems to have shrunk from 12Kb to 9Kb.
 - Registered application name, module name and star commands with RISCOS
   Ltd.
 - Module now uses error numbers from my offically allocated block, except
   for syntax messages which use the standard error number 220.

2.05 (29th August 2002)
 - Up to 4294967296 numbered screenshots may now be taken (previous limit
   was 999), and numbering now begins at zero.

2.06 (30th August 2002)
 - Reduced limit to 99999 to allow some room for a base leafname on filing
   systems with the old 10-character name limit.
 - Added warning query before accepting leafnames over this limit.
 - Fixed potentially serious bugs with insufficent memory being allocated
   for command strings - odd that this hadn't come to light previously!

2.07 (10th November 2002)
 - Recompiled using the official Castle release of 32-bit Acorn C/C++.
 - Corrected mistake in !Run file where the CallASWI module was not being
   loaded on RISC OS 3.6, despite being required on all OSes prior to 3.7.

15th March 2003
 - Recompiled module without stack-limit checking and embedded function
   names (both redundant in SVC mode), saving a little time and memory.

2.08 (22nd May 2003)
 - Fixed a potentially serious bug where 2 bytes of RMA were corrupted every
   time a screenshot was taken! It is likely that this dates from the
   increased length of filename suffix in version 2.05 and upwards.
 - Front-end gives a more sensible response to an error on
   Toolbox_Initialise (doesn't rely on the Messages file, which isn't open).
 - To prevent a huge backlog building up the filming ticker code no longer
   queues more than 5 CallBacks (screenshots) at a time - if the computer is
   slower than the configured frame rate then too bad.

2.09 (27th June 2003)
 - Now broadcasts Message_WindowClosed before opening the Setup dbox, on the
   off-chance that it has been iconised (though you would need an external
   iconiser to do this).

2.10 (28th June 2003)
 - Now changes the graphics window temporarily so that the whole screen is
   saved rather than just the contents of the current graphics window.

2.11 (9th September 2003)
 - Re-released as open source software under the GNU General Public Licence.
 - Formatted the manual text for a fixed-width 77 column display (Zap's
   default).
 - !Run file now requires version 5.43 of the SharedCLibrary, since that is
   the earliest version documented as supporting C99 functions.
 - Now uses "NoMem" from the global messages file rather than our own error
   message.

2.12 (20th September 2003)
 - Fixed a bug in the Resource file where clicks on the 'Info' entry of the
   iconbar menu would cause the application to quit.
 - Tidied the design of the Setup dbox to make it more compact and realign
   the 'Cancel' and 'Set' buttons on the right.

2.13 (2nd March 2004)
 - Recompiled with release 9 of CBLibrary.

2.14 (21st August 2004)
 - Moved to new-style CBLibrary macro names & made changes necessary to
   compile with release 11 of this library (e.g. all macros are now defined
   as expression statements, so trailing ';' required).
 - Removed moronic code that forced the input focus to the background
   of our setup dialogue box whenever a mouse click was detected. This was
   sabotaging any attempt by the user to place the caret by clicking on one
   of the two writable fields! The problem may have shown up due to changes
   in the toolbox's Window module (ill effects observed with version 1.97).
 - Clicking in blank areas of the setup dbox will no longer give it the
   input focus - only clicking within one of the writable icons will. Also,
   the default focus is now the 'Save location' writable field rather than
   the background of the dbox.

2.15 (16 Sep 2005) [module version 2.12]
   Updated ResFind from version 2.01b to latest version 2.12 (improved
    support for truncated country names & long paths).
   No longer requires the new (C99, APCS-32) shared C library or a version
    of the floating point emulator that supports LFM/SFM instructions.
   Fixed bug in *SGrabFilename where memory holding existing file name would
    leak if insufficent memory for new name.

2.16 (19 Apr 2006) [module version 2.13]
   Major internal changes to the ScreenGrabber module to avoid using
    OS_SpriteOp 2 and hence remove the necessity to change the VDU graphics
    window from a callback (which could have interrupted any multi-byte VDU
    command being issued by the foreground process).
   As a consequence of the above change, the old caveats about desktop use
    potentially causing an undesired Wimp command window no longer apply.

2.17 (08 Jun 2006) [module version 2.14]
   Extended the *SGrabHotKey command to allow users to configure which key
    triggers screenshots.
   Added the facility to save settings from the front-end into an Obey file
    of commands to configure the ScreenGrabber module directly.
   Fixed a bug where *SGrabPalette (with no arguments) and *SGrabStatus
    were displaying the hot key enable state instead of whether to save
    palettes.

2.18 (23 Jun 2006) [module version 2.14]
   Added a 'Save' button to the Choices dialogue box. This allows the state
    of the front-end to be retained between sessions, which was not possible
    by the old technique of saving an Obey file of star commands.
   To avoid confusion with the existing facility, renamed the 'Save setup'
    menu item as 'Save script'.
   The front-end no longer accepts an empty string as the save location for
    screenshots. This had previously caused the module to display the old
    file name because that is the action of *SGrabFilename with no parameter.
   Fixed a bug (which perhaps never manifested before) where gadgets in the
    Choices dialogue box were not faded as appropriate unless an error had
    just occurred.
   Increased the maximum recording interval that can be set by the front-end
    from 1 to 60 seconds.

2.19 (16 Jul 2006) [module version 2.14]
   Added commands in the !Run file to ensure that the SaveAs module is
    loaded. This prevents the error 'SWI &82BC0 not known'.

2.20 (09 Sep 2009) [module version 2.15]
   Now recognises the 64 thousand colour screen modes (RGB 565 format)
    supported by RISC OS 6 and saves sprites with the appropriate type (10
    instead of 5), so that colours are reproduced correctly.
   Extended the front-end to allow users to configure which key will
    activate ScreenGrabber, instead of having to resort to the command line.
   Holding down the hot key will now save a stream of screenshots instead of
    just one.
   Hands-off recording can now be activated by holding down Ctrl whilst
    pressing the hot key, instead of having to configure a different mode of
    interaction.
   It is now possible to configure a preference for encoding the colour depth
    and dot density of sprites using an old-style mode number or new-style
    type specifier.
   Enabled the usual Escape key shortcut to activate the 'Cancel' button in
    the Choices dialogue box.
   The front-end now silently ignores lines of a configuration file which
    consist entirely of white space.
   When the !ScGrabber application is 'seen' by the Filer, it now defines
    system variables for Castle Technology's proposed help system
    (ScGrabber$Description, ScGrabber$Publisher, etc).
   Added a new star command to allow the module to be fully configured using
    a single command instead of requiring four or five.
   The *SGrabStatus command now displays any OS error that occurred in the
    background (e.g. 'disc full').
   SWI OS_ReadArgs is now used to parse command arguments. This ensures
    canonical RISC OS behaviour and allows use of evaluated expressions such
    *SGrabConfigure -keycode "20 / 2".
   Removed the module's service call handler: since we have to re-read the
    start address of the displayed screen bank every time that a screenshot
    is saved, there is little point in cacheing the values of the other VDU
    variables between one Service_ModeChange and the next.
   An automatic variable used in the implementation of *SGrabHotKey was not
    being initialised if the command argument matched a key name or could be
    interpreted as a number. Out of pure luck, the register concerned (v2)
    happened to be 0 after being used previously in the same function.
   Fixed a bug where the module's star command handler leaked memory that it
    had allocated from the module area for a copy of the command tail.
   Major tidy up of the source code, which now compiles without any warnings
    using the Norcroft RISC OS ARM C vsn 5.54 compiler.
   Added support for debugging using Simon P. Bullen's fortified memory
    allocation shell.

2.21 (11 Sep 2009) [module version 2.16]
   Fixed a bug which caused the module to save sprites with a bad type if SWI
    OS_ScreenMode 1 returned a pointer to a mode specifier block within the
    top 2 GB of address space. It was erroneously using a signed comparison to
    determine whether the returned value was a mode number or pointer
    (regression in version 2.15 of the module).
   The front-end now gives a more helpful error message if the system
    variable giving the location to write choices has not been set up.
   Reinstated commands in the !Run file to ensure that the SaveAs module is
    loaded (regression in version 2.20 of the front-end).

2.22 (18 Oct 2009) [module version 2.17]
   Reverted to caching mode variable values until the next Service_ModeChange
    because the current values are invalid if VDU driver output happens to be
    redirected to a sprite when a screenshot is grabbed.
   The module's finalisation routine no longer gives up if an OS error
    occurs; it still refuses to die but sets a flag so that it will die
    silently on the next attempt without repeating any finalisation steps.
   Changed the misleading label of the 'Record until release' option button
    to 'Record until stopped'.
   Updated the front-end application to accommodate API changes in release
    34 of CBLibrary.
   Updated the module to use some new SWI veneers and named constants
    provided by CBLibrary.
   The module now uses a CBLibrary macro SPRITE_RIGHT_BIT_LOG2 instead of
    custom code to calculate a sprite's righthand wastage from its width and
    and no. of bits per pixel.
   Removed unnecessary explicit initialisations from enumerators.

2.23 (21 Oct 2009) [module version 2.17]
   Updated the front-end to use additional MessageTrans SWI veneers provided
    by release 37 of CBLibrary.

2.24 (26 Jan 2010) [module version 2.17]
   Fixed a minor bug in the front-end, which would have failed silently if
    commands couldn't be written to an Obey file but no OS error had been
    trapped.
   Removed dynamic dependencies from the distributed Makefiles.

2.25 (07 Jul 2010) [module version 2.17]
   Specified the appropriate switches to prevent the Norcroft C compiler
    from generating unaligned memory accesses incompatible with ARM v6 and
    later (for RISC OS on BeagleBoard).
   Added a few new assertions.
   Defined several 'magic' values as named constants.
   No longer uses deprecated CBLibrary macro names.

2.26 (04 Mar 2012) [module version 2.18]
   Fixed a minor bug in *SGrabConfigure where any two of the arguments
    [-Interval <centiseconds>|-AutoSync|-HalfSync] were accepted instead of
    generating an error.
   Made the star command handler more data-driven. Consequently the module
    is 2.56% (456 bytes) larger.
   Removed references to the bigfoot internet domain and added a web button
    to the 'About this program' window.

Licence and Disclaimer
======================

  This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public Licence as published by the Free
Software Foundation; either version 2 of the Licence, or (at your option)
any later version.

  This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public Licence for
more details.

  You should have received a copy of the GNU General Public Licence along
with this program; if not, write to the Free Software Foundation, Inc.,
675 Mass Ave, Cambridge, MA 02139, USA.

  If you did not receive source code with this program then you can download
it from my web site (see 'Contact details').

Credits
=======

  ScreenGrabber was designed and programmed by Chris Bazley.

  The front-end application uses CBLibrary, which is (C) 2003 Chris Bazley.
This library and its use are covered by the GNU Lesser General Public
Licence. You can obtain CBLibrary with source code by downloading it from my
web site (see 'Contact details').

  My thanks to the ever-helpful guys on comp.sys.acorn.programmer for their
advice when I ran into difficulties, in particular Ian Jeffray, Stewart
Brodie and Justin Fletcher.

  Thanks to Tony Houghton for generously supplying sourcecode with his
application FormText and his module SmartDir, from which I learned a great
deal about the toolbox and writing modules in C.

  Olaf Krumnow and Herbert zur Nedden of the German Archimedes Group wrote
the ResFind program I use to find the correct resources for different
languages.

  The application name 'ScGrabber' (including associated sprites/system
variables), the module name 'ScreenGrabber', and the set of '*SGrab'
commands have all been officially registered with RISCOS Ltd.

Contact details
===============

  Feel free to contact me with any bug reports, suggestions or anything else.

  Mail:  Mr C.J. Bazley
         139 Church End
         Cambridge
         CB1 3LF

  Email: mailto:cs99cjb@gmail.com

  WWW:   http://www.kingfishercorner.eu
