                                   QuickSnip
                                   =========

               QuickSnip is a quick and dirty screen snipping tool


Compatibility
=============

Two versions:

1) QuickSnipi_obj only needs the Pointer Interface (PI) V2, but not
necessarily the Window Manager (Wman). No other special toolkits are
needed for this executable to run under SMSQ/E.

2) QuickSnip_obj needs PI and Wman and also needs EasyPointer's ptrmen
pre-loaded.

As both these programs are compiled with Q_Liberator, they also require
Qlib_run V3.36+ or equivalent pre-loaded.

On plain Qdos youll also need TK2 and one or two of my Compatibility
toolkits, SCR_bin, or similiar with the SCR_XXXX commands and DISP_TYPE,
and PEEK & POKE or similar with the PEEK$ command.

Only display modes 0/4, (8), 16, 32 & 33 are supported. Mode 2 (B&W) has
not been implemented although it probably could be. I just dont have the
hardware to test.

Note: Mode 8 doesnt quite work as it should in all situations. Perhaps
      someone who needs this (I dont!) might have a go at fixing it?


Usage
=====

Best put on a Hotkey, eg to put it on Hotkey ALT + CTRL + s:

        ERT HOT_CHP1(CHR$(19), "<path>QuickSnip_obj" [; <colour>]

otherwise use EX, as in

        EX <path>QuickSnip_obj [; <colour>]

If no colour (1..7) has been specified the box frame colour defaults to 7
(white). For a more fanciful frame colour, a single charcter can be
given instead. The code of that character will be used to draw a stippled
frame.

Once the program starts simply start moving the pointer to resize the frame.
(If no frame appears initially, HIT once or twice and move the pointer
down and to the right.)

HIT to toggle between Move and Stretch mode.

Once satisfied of the area to be snipped, DO (or press <ENTER>) to save it.

Snips are saved to ram1_QSNPn_pic, with n incrementing on each save from
0 to 9, whereafter the program errors and the snip is not saved. Simply
move or delete the snips to start over again. (Did I mention that this was
a quick and dirty program?)

You can configure the default snip save name and location by using the
standard Config or MenuConfig program. You must enter the full path and
file name, but do not add the _pic extension, as this will be added by
the program.

Note: While the program is running avoid using CTRL + c,  Hotkeys,
      etc, as the focus will be lost and may be tricky to get back!
      In other words: prepare the screen for what you wish to snip
      before invoking QuickSnip.

There are a few keystrokes you can use for extra functionality:

<ESC>    - Quit without saving
     - The cursor keys can be used instead of the mouse.
A, a     - All. Ignore the box and save the whole screen
B, b     - Bottom. Move or stretch to bottom of screen
R, r     - Right. Move or stretch to the rightmost edge of the screen
<ENTER>  - Save the area outlined by the box (same as mouse DO)
<SPACE>  - Toggle between Move and Stretch mode (same as mouse HIT)

Note: Under Qdos/SMSQ the pointer doesnt like going to the rightmost edge
      of the screen and also shows some reluctance to go to the bottommost
      edge. To coax the pointer to do so press the letter r or R
      (for Right) or b or B (for Bottom). It may take a few attempts before
      it ventures all the way. Press <ENTER> then to save the snip to avoid
      moving it again with the mouse.


Programming notes
=================

The source code for the various toolkit commands can be found at
Knoware.no.

As it stands, the BASIC source program can be EXECuted under SMSQ/E, but
cont be RUN in SuperBASIC without modification. (Note that it messes with
channel #0. Not a problem with SBASIC daughter jobs but could be
troublesome in SuperBASIC or in SMSQ/E's main console.)

Only the EasyPointer version has its own special sprite as it is a feature
of Wman to have different sprites for different windows and it was a
design goal to use as few external resources as possible.

Note: For very large screens you may run out of stack space when trying to
save the full screen. Increase the stack size (rem $$stak=nnnn) and
recompile the program. Use SCR_LLEN * bytes per pixel + extra as a guide
to how much you many need.


Program status
==============

V0.01, pjw, 2026 May 5

          Conditions of use and DISCALIMER as per Knoware.no
