QL Software
Snip
====
Snip a piece of screen or one of a job's windows and save it to file
Requirements
Installation
Usage
Area selection
Mouse mode
Pick mode
Cursor mode
FSEL - The file selector
Configuration
Overview
Item details
Root Directory Configuration
Troubleshooting
Program Notes
Software Status
Requirements
============
This utility runs under SMSQ/E only, preferably a recent version. It should
run in most screen modes: 0, (8), 16, 32, 33. (QL mode 8 should work, but
there are no mode 8 sprites, so it looks a bit odd.. Atari mono: not tested
and so not currently supported.)
Snip requires the following external toolkits:
Env_bin (Environmental variables)
Qlib_run or equivalent
EasyPointer's ptrmen_cde V4.10+
JMS'es Qmenu: menu_rext
I make no apologies for requiring these essential systems extensions! They
must all be loaded prior to using this utility; ideally, they should be
included in your boot file.
Make sure that you use the latest versions of these toolkits. They can
all be found online (See the Knoware.no Contacts page if required.) Visit
their author's/maintainer's web sites and see what other goodies they may
have to offer. And let them know you appreciate their work!
However, just this once, Ive included them with this distribution. See
the Installation section for details.
Snip also uses the FSEL file selector utility, a copy of which is included
here. Updates and documentation can be found at Knoware/Files if wanted.
This document doesn't provide details about how to use these tools beyond
what is relevant to Snip.
Snip is under permanent development, so you may find it a bit rough round
the edges. It may never reach "production quality" standards, as that is
just too much effort for no reward. You have the source code, so you can
fix anything you don't like!
However, if you discover bugs and the like - or even if you just happen to
like Snip, I should like to hear from you!
Installation
============
Note: If you are updating/upgrading from an earlier version you may first
want to move your current snip_cfg configuration file out of the way and
use any settings from there as reference. All other files can just be
overwritten by the later version.
Unzip the SnipXX.zip file into a suitable sub directory, eg to win1_util_
Unzip creates a sub directory under that called ..snp_ which, again,
contains some further sub directories:
win1_util_ unzip directory (for example)
snp_ program directory (created by unzip)
asm_ assembler source directory
bin_ the toolkits mentioned above
After installing, you could do worse than run the ..snp_boot program from
the main SBASIC console (ie Job #0). It checks that your system has the
necessary toolkits loaded and if not, loads them for you! Make a note of
any missing toolkits it loads and add these to your standard boot file.
If you are updating/upgrading from an earlier version you may want to
configure the program before continuing. If this is your first install you
should be good to go with the default settings for now.
Usage
=====
Snip is best attached to a hotkey, for example, given Snip being located
at win1_util_, and the Hotkey 'c' being free (for example):
ERT HOT_RES1('s', 'win1_util_snp_Snip_obj' [; '<other root>'] [, 'Snip'])
would attach Snip to ALT s, with an alternative location for the config
file at <other root> (optional), with the Snip Thing called 'Snip'
(optional).
Area selection
==============
Given the above details, pressing ALT and s will display a square box on
your screen. Also, the Info Box will appear somewhere on the screen. This
displays the size and origen of the area to cut out. It will not be
included in the snip, however, even if part of it is inside the box. The
position of the Info Box can only be changed in snip_cfg, not
interactively.
Three alternative area selection methods are available:
1. Mouse mode
2. Pick mode
3. Cursor key mode
Note: Snip saves the area under the box frame as well as whats inside
the box!
Mouse mode
----------
Grab (HIT & HOLD) any edge or corner of the selection box with the mouse to
stretch it to the size you want, or grab the inside of the box to drag it
to some suitable starting point. When satisfied, let go and DO inside the
square to terminate. The file selector then pops up and offers you the
option to edit the file name (if desired) and save the file.
Note: The terminating DO prepares the snip to be saved in the configured
default mode, ie either compressed or uncompressed. To override this type
'C' or 'c' instead of DO: Terminating with 'C' will always save the snip
compressed, while 'c' will always save it uncompressed.
In mouse mode ESC quits the program without saving.
Pick mode
---------
With the mouse, click outside the box. The dynamic Target sprite should
appear. HIT any window or partial window to bring it to the fore. The
window or sub window you have selected should momentarily "flash". If you
now DO that (sub)window, the (sub)window selected should be inside the box.
You can now trim the box using the mouse or cursor keys to the desired
size.
While in Pick mode the only key presses acted on are ESC, SPACE/HIT and
ENTER/DO. No other key- or mouse-presses are honoured, including CTRL c.
ESC exits Pick mode and returns to box mode.
Note: Windows that are not "well-behaved" (or "managed" in PE parlance),
may cause the pointer to be captured. Move the mouse to get the pointer out
of that window. A second attempt may then be successful..
Cursor mode
-----------
You can also use the cursor keys to resize the box (or to trim the box
more precisely).
Cursor keys
without modifiers - move the box
with SHIFT - moves the box in larger increments
with ALT - moves the box to the edge(s)
with CTRL - stretch the box in the given dimension
with CTRL + SHIFT - stretch the box in larger increments
with CTRL + ALT - stretch the box to the edge
In cursor mode to resize you need to choose the side to operate on. Press
L/l => Left side
R/r => Right side
T/t => Top side
B/b => Bottom side
The selection remains in force until changed. If sound is switched on, a
valid key press is acknowledged with a confirming beep.
ENTER saves snip in default mode (compressed or uncompressed),
while
SPACE saves the snip uncompressed.
The program slips out of cursor mode after about one second after the last
cursor mode action! Thus waiting too long before pressing ENTER or SPACE
wont work: You need to pres a cursor key again to re-enter cursor mode -
or use the mouse as above. Practice makes perfect!
Some key presses are available in both mouse mode and cursor mode:
TAB centres the box on screen
'a' and 'A' select all => whole screen
'C' saves the snip compressed
'c' saves the snip uncompressed
SPACE and ENTER are only available in cursor mode. You can,
however, do a quick press on a cursor key and immediately follow
it with SPACE or ENTER, if you prefer.
FSEL - The file selector
========================
FSEL is the standard Knoware file selector program that allows programs to
make use of JMS'es excellent Qmenu FILE_SELECT$ utility - even when the
application program doesn't have its own window, or the application
program's window is too small. This should be available somewhere and its
whereabouts set in snip_cfg. A copy is included with the snip_obj program.
If FSEL is not available for some reason a text entry window is displayed
instead. A file name suggestion is displayed for you to edit or accept.
Note the extension! _pic implies an uncompressed PIC file, while _pac
implies a compressed PIC, namely - you guessed it - a PAC file. The
correct extension should be used to avoid tears later!
PAC files can be viewed using my QV utility. This format may be adopted by
other graphics viewers in due course. PIC files may be viewed with QV or
many other graphic file viewers, such as Bob Spelten's excellent SQRview.
Note: PIC/PAC snips are saved using the current screen mode; 0, 8, 16, 32,
or 33. QV only runs under GD2 modes 16..33, but it can display PICs and
PACs in all of these modes, even if it is running under a different mode.
The default filename suggestion is <path>_snip_p*c (where p*c is PIC or
PAC as appropriate).
Initially the path is as set in snip_cfg, but it later changes to the last
path used.
Snip doesn't do overwrites: If a file of the same name as given already
exists, the filename is automatically suffixed with an index of 0..9, eg
snip0_p*c, snip1_p*c, .. After snip9 - or if you press ESC before
completing the save - the save will be aborted with a rude noise (provided
sound is switched on) and the snip is lost.
Configuration
=============
To start with you can just leave these configuration setting as they are!
Overview
--------
The main configuration is done via a small text file, snip_cfg, which must
reside in the same directory as the Snip_obj itself (the so called Home
Directory). However, you CAN configure a different home directory using
(Menu)config, if you need to. (See further down.)
The configuration file looks like this:
SNIP02
xorg = -1 x-origen of outline box (-1 => current
yorg = -1 y-origen pointer position)
boxbd = 4 * box border thickness (1..8)
boxx = 100 * box x-size at startup (boxbd x 4 .. 200)
boxy = 100 * box y-size at startup (boxbd x 4 .. 200)
colour = 7 * box colour (QL colours 0..7)
sound = 1 Sound feedback: none-zero => on
comp = 1 default image compression: none-zero => compress
timeout = 10 timeout before HOLD kicks in, in 50th seconds
* File selector. (Path name may be replaced by a * => configured Home):
fselth = FSEL FSEL Thing name - prioritises this if present
fsel = *Fsel_obj name and location of FSEL
fselszx = 400 FSEL x-size
fselszy = 220 FSEL y-size
fselpal = 0 FSEL palette
fseldir = ram1_ Default directory for saved snips
asleep = asleep E: asleep D: schlafend, F: dormant, ..
(QPAC2 language dependent)
* Info Box position (Info Box: See below)
posx = 0 * Key: 0 => centre, +X => 0 + X, -X => width - X
posy = 20 * Key: 0 => centre, +Y => 0 + Y, -Y => bottom - Y
* Note: Not all possible settings shown above will work in all modes and
screen sizes!
The following rules apply to the config file:
You can edit it with a plaintext editor.
Blank lines are ignored.
Lines starting with an * are ignored.
Only the values after the = sign may be edited.
Values may not contain spaces. Values are terminated by the first
none-quoted space. Anything after that space is considered a
comment and is ignored.
Lines, including comments may be up to a maximum of 100 characters in
length.
Item details
------------
You only need to read the following section if anything above was not
clear!
SNIPxx
This is the file ID. It must be the only item on the first line,
and it must not be altered!
xorg and yorg
If xorg is given as -1, then yorg is assumed to be -1 also.
This means the box pops up at the current pointer position.
xorg and yorg can have another flag value: If either or both are
-2, those positions are centred on screen.
xorg/yorg can also be any other positive value between 0 and the
maximum screen dimension minus the box size.
colour
Since the box is xored with the screen, only a limited number of
colours are useful. Values from -256..255 are valid, default 7
(nominally white).
timeout
The number of frames (50th of a second) before HOLD kicks in (See
Mouse Mode, below)
The remaining items relate to FSEL, the file selector. If you already use
FSEL V.10 or greater, you can enter its file location instead and delete
..snp_prg_Fsel_obj
fselth
Set the Thing name of Fsel here (normally FSEL, unless you changed
it. See the Fsel manual for details of that, if you like.) If the
FSEL Thing is present it will be used instead of Fsel_obj, as this
is faster and more convenient. If the setting is left blank, or the
the FSEL Thing is not found as Snip starts, the Fsel program file
will be used instead.
fsel
Here you must set the full name and location of the FSEL executable
if you wish to use that instead of the FSEL Thing. (The setting is
ignored if the FSEL Thing is set and is present.) However, if
Fsel_obj is located in the home directory you can skip the
directory and replace it with an asterisk * (see below for more..)
fselszx/fselszy
The x- and y- size of the FSEL window. Make sure that it fits
within the display, ie screen!
fselpal
Here you can determine the palette for FSEL to use: 0..3
fseldir
This is the default device and/or directory to use for saving your
snips
asleep
This is required to wake FSEL if you should happen to put it to
sleep while it is in use. Due to a quirk this is different
depending on the language of your QPAC2:
English asleep, German schlafend, French dormant, .. (Any other
languages versions of QPAC2 out there.)
posx/posy
These represent the position of the Info Box. If a coordinate is
given as 0 it implies that that dimension is to be centred on the
display. A positive coordinate implies the box is to be displayed
that number of pixels from the left or top edge of the display. A
negative coordinate implies the box is to be displayed that number
of absolute pixels from the right or bottom of the display.
posx/y = 0/0 => Info Box is displayed in the middle of the screen
posx/y = 20,20 => Info Box is displayed at x=20, y=20
posx/y = -20,0 => Info Box is displayed 20 pixels from the right
and half way down the display
The default and fall-back setting is 0, 20
Note: Odd values may not work in QL modes.
Note: If you don't want to use FSEL, or if FSEL is not found, a Qmenu text
box is proffered instead. (But you still need Qmenu, or Snip will error).
Root Directory Configuration
----------------------------
In QL parlance, the Home Directory is the directory in which the program
resides. This is also where Snip expects to find its configuration file -
unless instructed otherwise.
Different platforms may have different requirements, eg different screen
sizes or storage mediums. So if you mirror your setup across different
platforms, it may not be convenient to use the same configuration file;
each platform may need its own settings. Therefore in Snip you can
configure a different location for your "root directory" than your home
directory. Use the standard Qjump Config program for this, or JMS's
MenuConfig. Alternatively, you can supply the root directory on the command
line, thus:
EX <path>_Snip_obj; <my alternative root>
The order of precedence is:
1. If a valid directory is found on the command line, use that, else
2. If a valid directory was configured in the executable, use that, else
3. If there is a valid home directory, use that, else bomb out. You had
your chance!
Troubleshooting
===============
Q: On startup Snip bombs out with the error Not Found!
A: This implies that no valid root directory has been specified and Snip
can therefore not find its configuration file. To rectify this see the
section "Root Directory Configuration", above.
Q: On startup Snip bombs out with the error Invalid name!
A: This occurs if the Snip_cfg file is the wrong version or has become
corrupted. Check that this file is ok and has the version ID SNIP02!
Q: After using Snip my Window Move sprite looks different!
A: Should Snip be terminated "unnaturally", eg it crashed, or perhaps it is
still running quietly in the background due to the pointer having been
captured by an un-managed window, it may not have had the chance to restore
the normal Window Move sprite: Check that no Snip job is running (eg try
RJOB 'Snip', 0). Then start up Snip again and terminate it naturally (eg
ESC). That should put it right.
Q: In mode 8 all the Snip sprites show up as red crosses!
A: I didn't make mode 8 sprites for Snip. Sorry. But you can still use Snip
in the normal way under mode 8.
Q: I get a Qlib error citing SUSJB.
A: Some versions of SMSQ/E had a faulty SUSJB command. Pre V3.35 there was
no such command at all. The solution is to upgrade SMSQ/E to the latest
version or to LRESPR the SUSJB_bin toolkit from the ..snp_bin_ directory and
add it to your boot file.
Program notes
=============
I tried to get rid of ptrmen_cde since Snip now only uses a single
remaining command from this toolkit, namely SPRS (to set the (sub)window
pointer sprite). However, it proved difficult to achieve, so it will have to
wait until a possible future update. If you only load Qptr, and prefer it
that way, you could swap out SPRS with CH_PTR and recompile.
Software Status
===============
V0.05, pjw, 2022 May 07, FSEL as Thing, bug fixes, re-do of manual, Select all
Conditions of use and DISCLAIMER as per Knoware.no
QL Software