Snapper
-------
User guide

The full manual is in HTML format and may be more up to date. Use a
CSS aware browser (e.g. Netsurf) for best results.


Introduction
------------
Snapper is a versatile screen capture program. It allows you to save
an area of the screen as a sprite, or in PNG or JPEG format. Paint
already has such a 'snap shot' facility, at least for sprites. The
reason for having another program to do this job is that some of the
most common tasks, like saving the contents of a window or menu, are
messy using Paint, which requires the use of an imaginary rectangle
and a time delay.

Snapper was originally written by David Pilling, and supplied with his
scanning and image processing software suite. With the full agreement
and encouragement of David, Chris Johnson has taken on the maintenance
and development of Snapper, and the new version is now freely
available.

A consequence of this is that all correspondence about Snapper should
now be directed to Chris Johnson (Email: chris@chris-johnson.org.uk),
and not to David.


Installation
------------
For a new installation, simply drag and drop the Snapper application
into the directory of your choice.

If you have a previous copy of Snapper then move the old version of
Snapper somewhere safe and replace it with the new version.


Usage
-----
Snapper is run in the usual way by double clicking on its icon. It
will install on the icon bar.


The icon bar menu
~~~~~~~~~~~~~~~~~
Info - shows application information, including the version number,
and also contains a Web button to check the download site for later
releases.

Help... - opens the html help file (this one).

Control - will open the Snapper control window (see below). The
control window can more easily be opened by clicking on the icon bar
icon with Select.

Save choices - will save the current Snapper configuration. The option
to save the configuration is placed on this menu, because it will also
save the position and size of the snapper control window and the snap
area.

Save choices will save the following details.
 * snap mode setting
 * show pointer setting
 * move pointer setting
 * the key combination to trigger a save
 * the save method
 * the save path
 * the fill colour for the area snap
 * whether the snap area coordinate window will always open when the
   snap area is set
 * whether the target window will be brought to the front before
   snapping
 * the position and size of the control window
 * the position and size of the snap area box
 * whether to use the desktop font to label the area top bar
 * the default output format (sprite, png, jpeg)
 * the jpeg quality setting
 * whether to add the /jpg or /png extension to files saved in those
   formats

These settings are described in detail below.

Quit - will remove the application from the iconbar.


The default control window
--------------------------
The default control window shows 4 buttons that can be used to select
the mode in which the program will work.

Screen
~~~~~~
In this mode the entire screen area will be captured each time.

Window
~~~~~~
In this mode the window under the mouse pointer will be captured. This
includes the window title bar and scroll bars. This was the mode used
to capture the screen shot of the control window, above.

Contents
~~~~~~~~
In this mode the contents of the window under the mouse will be saved,
without any of the window furniture. For example, when this mode is
used to capture the control window, this is the result.

Area
~~~~
In this mode, a box will appear marking an area of the screen. The
area inside the box will be saved. The area can be moved or resized by
dragging on the sides or corners.

Drag on a corner. Dragging on any of the corners will resize the
rectangular area by moving that corner. If the control key is held
down while dragging any of the corners, the area will expand or
contract symmetrically about the centre point. If the shift key is
held down, then dragging any corner will move the whole area rather
than change its size.

Drag on a side. Dragging the side of the area will move the area
around the screen. If the shift key is held down while dragging, the
area will be resized by moving only that side. In addition, double
clicking on any side of the area will open the coordinate display
window (more details below).

When the area is moved or resized, the snap area will be constrained
to the screen boundaries, although to fully include the screen edge,
the corresponding border will be just out of view off screen. Note
also that the area follows the normal wimp convention for dragging,
i.e. dragging with SELECT will bring the area to the top of the window
stack, dragging with ADJUST will retain its original position in the
window stack.

The size of the area to grab (in pixel) is shown in the top bar of the
bounding box. The values update in real time as the box is resized.

If you need even more precise control over the position and size of
the snap area, then you can use the coordinate display window (more
details below).

Snap button
~~~~~~~~~~~
Finally the 'Snap' button triggers the screen capture. The save can
either be

1. via a standard save box
2. directly to a preconfigured directory
3. to the global clipboard
4. immediately filer_run

More details on saving are given below.

Obviously the Snap button is not always of use. For the Window and
Contents modes, you would always end up with a picture of the Snapper
control window. To get around this, it is also possible to trigger
screen capture with a key press. By default this keypress is to hold
down the left hand Ctrl and Alt keys.


The full size control window
----------------------------
Toggling the snapper window to full size (click on the top right
corner icon) reveals more options, as shown in the window at the right
and sections of the window below.

Key trigger
~~~~~~~~~~~
This allows you to set which key press combination will start the
screen capture. You need to pick a combination that will not clash
with other apps using hotkey combinations, such as Keystroke. You can
now use the left and right SHIFT, CTRL, ALT and LOGO keys (some
keyboards do not always have both LOGO keys). It should be possible to
pick a key combination that does not interact with other software.
Note that it is not necessary to choose a two key combination. You can
select as many (or as few) keys as you like, although two adjacent
keys is probably the best option for normal use.

Pointer
~~~~~~~
There are two options. Move will remove the pointer from the screen
area before capturing the screen. This is useful if you want to
capture a menu. With move selected, the menu will appear without the
usual inverted selection where the pointer is. Show will display the
pointer in its correct position on any captured images. There is
further information on the hints page.

Note for MoreDesk users: An option in MoreDesk is to use 'Alt key +
mouse moved to edge of screen' to navigate to the next screen. If you
have the Snapper option 'Move' set, and the Alt key is one of your
trigger keys, then when the pointer is moved to the bottom left of the
screen during the grab, and the Alt key is still being held down,
MoreDesk will detect this and may change screens! You then end up
grabbing an area of the wrong screen.

Fill
~~~~
This allows you to specify the fill colour for the area window. If the
fill is set as Trans (transparent) then everything visible within the
area border will be captured. If there is a fill colour set, then only
windows in front of the area will appear. The area window follows the
usual rules for window order. Dragging it around with adjust will
preserve its position in the window stack. Dragging with select will
bring it to the front. The fill colour can be chosen by clicking on
the menu button to the right of the set colour and then making a
selection from the menu. The colours are limited to the standard wimp
colours There is further information on the hints page.

Save options
~~~~~~~~~~~~
A full description of the options for saving files is given below.

Bring target window to front
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If other windows overlay part of the target window then these will be
shown when the window is snapped. If this option is selected, then
Snapper will bring the target window to the front before snapping, and
then return it to the original position in the window stack after the
snap.

More settings...
~~~~~~~~~~~~~~~~
Clicking on this button will open the 'More settings' dialogue, shown
below.


Options for saving the screen snap
----------------------------------
Saves from within the desktop
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In the case of saves from within the desktop, there are four ways of
completing the snap. The method is set by clicking on the menu button
and selecting from the resulting menu, which is shown below. You will
need to save choices from the iconbar menu for the new setting to be
remembered after Snapper is quit.

Use Save As
~~~~~~~~~~~
A standard SaveAs dialogue will be opened when you click on the Snap
button or use the key trigger. You can select the image filetype for
the save by selecting the appropriate button in the SaveAs dialogue as
shown below. The icon (which should reflect your choice of filetype)
may be dragged to a directory viewer to save to disc, or directly to
an application that is able to load that type of file. Once a save has
been made to disc, then the path and filetype are remembered, so that
if subsequent saves are required in the same directory, it is possible
to click on the OK button to save immediately. The filename numerical
suffix will increment with each save so the previous file will not be
overwritten.

Use Save path
~~~~~~~~~~~~~
When you click on the Snap button or use the key trigger the save path
is used directly without opening a SaveAs dialogue, and the file is
saved immediately in the designated directory. The filename suffix
will increment to prevent previous files being overwritten.

In order to set the Save path to other than the default (which is set
to the same directory as that holding the Snapper application), you
have three options.

1. Enter the full path manually and press RETURN
2. Click on the menu button just to the right of the save path
   writable field. This will open a save box. The icon must be dragged
   into the directory in which you want the images to be saved
3. Drag the destination directory from the filer window into the save
   path writable field

Whichever method you use, you will need to save choices from the
iconbar menu for the new setting to be remembered after Snapper is
quit.

The image file format for direct saves using the Save path is shown in
the lower field and is selected by using the popup menu button to the
right of the field. The image file types are sprite, draw (a sprite in
a drawfile wrapper), PNG or JPEG.

Use clipboard
~~~~~~~~~~~~~
In this case, when the snap is made, the captured sprite is held in
memory, without an actual save being made, and Snapper claims the
global clipboard. The snap may then be pasted into another application
that supports the global clipboard and will paste sprites. Examples
are OvationPro and TechWriter.

When using the clipboard it is only possible to paste as a sprite (or
drawfile wrapped sprite). This is due to the png and jpeg library
routines used here writing the converted image directly to a file. In
addition, very few, if any, RISC OS applications will request the
clipboard contents as png or jpeg type.

Filer_Run
~~~~~~~~~
With this setting, Snapper will save the snap into the configured save
directory (as above for Use Save path), but will then issue a
Filer_run command for the file. The snap should then be directly
loaded into the configured application for running that image format.
The default for sprites will be !Paint. For formats such as PNG, a
suitable application must have been booted, so that the run action for
the file has been set up.

Capturing the complete desktop screen without the snapper control
window being visible

There are two options:
1. The simplest way is to hide the snapper control window behind
   another window before using the hotkey combination to make the
   snap. This way you have the full range of save methods and save
   filetypes available.

2. Make sure that Screen is the mode selected. The control window can
   then be closed and the capture initiated with the key trigger. In
   this case it is the module which deals with the save as described
   in the next section. The snap will immediately be saved into the
   configured save path directory as a sprite. You cannot change
   either the save method or filetype.

Capturing the complete desktop screen without even the snapper iconbar
icon being visible

This is a modified version of the second option above. Make sure that
Screen is the mode selected. The control window can then be closed,
and Snapper quit. Again it is the module which deals with the save,
which is initiated using the key trigger, and the sprite will be saved
into the configured save path directory.

Saves from outside the desktop
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you have a program that does not run in the desktop, but takes over
the screen and runs as a single task, then you can only save in one
way. By choosing Screen mode, and ensuring that the Snapper control
window is closed before leaving the desktop, screen captures can be
achieved from outside the desktop, by using the trigger key
combination. The configured Save path will be used to save the screen.
In this case the screen will always be saved as a sprite.

This full screen save from outside the desktop is implemented by the
Snapper module. This is contained in the module Spell (it shares some
code). The module supports one *command, viz. Snapper_Key, which is
followed by a number formed from one bit for each of the Left and
Right Alt, Ctrl, Shift and Logo keys. So Left Alt contributes 1, Right
Alt 2, Left Ctrl 4, Right Ctrl 8, and so on up to Right Logo 128.
Files will be saved to the system variable <SnapperFile$Dir>. This
information should allow the use of the module outside of Snapper.

More information about the save path may be found in the
hints/tutorial section.


More settings
-------------
Auto show area coordinates
~~~~~~~~~~~~~~~~~~~~~~~~~~
If this option is ticked, then the coordinate display window will be
opened every time the area mode is selected. If not ticked, then the
area coordinate window will not open when the Area mode is selected,
but can be opened at any time by double clicking on the red border of
the area (more details below).

Use desktop font
~~~~~~~~~~~~~~~~
If this option is ticked, Snapper will use the configured desktop font
to show the coordinates in the top bar of the area outline. If not
ticked, then Snapper will default to using the Homerton font at 12 pt.

Note that Snapper uses the  (multiplication) symbol in the top bar of
the area outline. Some fonts do not include a full set of characters.
When a desktop font is configured, Snapper checks the 'width' of this
character and if it is very close to zero, probably meaning it is
absent, it falls back to using lower case x. There may be occasions
when a font includes a different character in the position
corresponding to the  character in Latin-1. If this is the case, then
switch off the desktop font - the ROM based Homerton font will then be
used.

Add filetype extension
~~~~~~~~~~~~~~~~~~~~~~
If this option is ticked, then when saving the snap in either PNG or
JPEG format, Snapper will automatically add the /png or /jpg extension
to the filename.

JPEG quality
~~~~~~~~~~~~
This is the compression factor (and hence quality of image) that will
be used when saving the snap in JPEG format. The default setting is
75, but can be set in steps of 5 between 20 and 95, by means of the
bump arrows, the lower the quality setting, the poorer the quality of
image. Quality settings less than 20 can introduce various artifacts
and banding and are not reccomended. Settings above 95 give much less
compression. If very high quality is necessary, then use a lossless
compression method, ie PNG.

Convert sprite format
---------------------

Save sprite in RO 3.5 format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ROOL have introduced a new sprite format (newer than the so-called new
format introduced with RISC OS 3.5) and recent versions of RISC OS 5
make use of this. In addition, the latest hardware, e.g. IGEPv5 and
Titanium, have the red and blue colours in the new sprites
interchanged. When you make a screen grab on such hardware, the sprite
generated will be in this new format. This may be of no consequence on
the hardware being used. However, older hardware/OS versions may not
understand the new format. In addition, a lot of older software cannot
display or manipulate such sprites, even on the new hardware. Snapper
therefore offers the option to convert these newest sprite types to
the older RISC OS 3.5 format before saving. The sprites should then be
usable on legacy hardware, OS, and software. This option must be
ticked for the sprite conversion to occur, otherwise the saved sprite
will be in the native format of the hardware and OS version.

Convert 64K to 32K sprite
~~~~~~~~~~~~~~~~~~~~~~~~~
RISC OS 6 first introduced the 64K colour depth screen mode and
sprites. While these can be viewed on RISC OS 5 and 6, they cannot be
used on RISC OS 4. If you are saving in the RISC OS 3.5 format, then
this option gives you the choice of saving either as a 64K sprite, or
as a 32K sprite. When ticked, the 64K sprite will be converted to the
32K version before saving. Remember, if the option Save sprite in RO
3.5 format is not ticked, then the saved sprite will be a 64K sprite
in the native format of the hardware and OS version, whatever the
setting of Convert 64K to 32K sprite.

To summarise
............

If the sprites are being converted from RISC OS 5 format to RISC OS
3.5 format then the following will apply.

32-bit 16M colour screen mode
Converted to a 32-bit 16M colour RISC OS 3.5 sprite with the red/blue
colours in correct positions

16-bit 64K colour screen mode
Converted either to a 16-bit 64K or 16-bit 32K colour RISC OS 3.5
sprite with the red/blue colours in correct positions

16-bit 32K colour screen mode
Converted to a 16-bit 32K colour RISC OS 3.5 sprite with the red/blue
colours in correct positions

16-bit 4K colour screen mode
Converted to a 16-bit 32K colour RISC OS 3.5 sprite with the red/blue
colours in correct positions

The area coordinate display window
----------------------------------
If the option Auto show area coordinates in the control window is
selected, then the coordinate display window will open every time Area
mode is selected. It can also be opened at any time by double clicking
anywhere on the red border of the snap area.

Shown in this window are the x and y coordinates of the bottom left
corner of the snap area, together with the width and height of the
area, all values being in pixel. These values are continuously updated
as the area is moved or resized by dragging on the red border.

The values can be set by typing in to the writable fields, or by using
the bump icons adjacent to the fields. The size/position of the area
is updated either as the bump icons are pressed, or when the up arrow,
down arrow or return key is pressed. The bump icons follow the usual
convention, i.e. holding down the shift or ctrl keys will increase the
step size, and using the adjust button will reverse the direction of
movement.

Changing the size or position of the snap area using the coordinate
display preserves the position of the snap area in the window stack.
If you need to bring the snap area to the front then you can use the
key press ctrl-F (the coordinate display window must have the input
focus, i.e. the caret must be in one of the writable fields for the
key to be recognised). In the same way ctrl-B will force the snap area
border behind all the other windows.

The coordinate window is always closed when the snap area is removed
from the screen. It can be closed at any time the snap area is showing
using the close icon in the title bar, and reopened by double clicking
on the red border of the snap area.


Contact
-------
All communication about Snapper should now be directed to Chris
Johnson (Email:chris@chris-johnson.org.uk). Suggestions for new
features are always welcome.

Web sites
~~~~~~~~~
David Pilling's web site is at http://www.davidpilling.com/, in
particular, the RISC OS section of the site is at
http://www.davidpilling.com/riscos.html.

Chris Johnson's web site is at
http://www.chris-johnson.org.uk/index.html, with his RISC OS software
at http://www.chris-johnson.org.uk/software/index.html.

Screenshots
~~~~~~~~~~~
It goes without saying that all the screen shots in these notes were
acquired using Snapper itself, either in window, content or area mode.



Licence
+++++++

Copyright (c) 2013, Chris Johnson and David Pilling
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

* Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.


THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


--------------------------------------------
This document last modified on 27th April 2016
