QL Software
QuickView
*********
Yet another QL graphics viewer program!
QuickView, or QV, is a no-frills graphics file viewing program - a spin-off of a
larger project that may one day see the light once a few issues have been
resolved.
Index
=====
Features
Quick Start
Requirements and Limitations
Toolkit extensions
Image file types
Group functions
Getting started
Usage
Starting the program
Window and display controls
Menu keystroke equivalents
Transformation keystrokes
F3 Menu
Screen Dumps (manual correction of)
Excuses
Command Line Options
File Types and Extensions
Config
Movement key codes
Selecting a suitable temp drive
A note about Root
Making QV part of your System
Troubleshooting
System crash
Qlib errors
Cannot find QV_cfg
The error window doesnt go away
Supported foreign format graphic doesnt display
All files show as Not Implemented (even when they shouldnt)
Screen dump issues
Theme, Palette, THB files
Sleep, asleep, btsleep
Blurred graphics
Graphics wont move in the window. Graphic wont resize
Group functions dont work properly
Acknowledgements
Program status
Features
========
QV is made to be started by some other program, such as a file manager, with
details of the graphic passed to it via the command line. It has no file
selector of its own, and only limited functionality: It is designed to VIEW
graphics files, not edit or manipulate them.
Supported files are pac, pic, psa and screen dumps of mode 0, 8, 16, 32, 33,
and 64, and foreign formats jpg, png, gif, zxd, and bmp*.
Larger-than-screen images can be down-scaled - Or view them full size by moving
the image within the display window using a mouse or cursor keys. Images can be
up- or down-scaled to fit the frame. Save the whole image or the visible part of
the image to file in the current display mode for faster loading next time.
A QV group is all running instances of QV with the same owner (or no owner).
Experimentally, certain "group functions" are implemented: Tile or cascade
multiple instances. Put them all to sleep or wake them all up - and finally:
kill them all off at once.
If you load QV as a Thing, only one instance of the code is loaded however many
instances are running.
* BMP is STILL not yet fully supported.
Quick Start
===========
Q: Why do I need a manual to run a "no-frills" picture viewer?! Windows doesnt
seem to need one: Just use it right out of the box!
A: Windows and one or two other OSes are now quite standardised, and almost all
applications that run under them comply with those standards. The UI is so
ubiquitous that "everyone" knows how to use them. Its like driving a car: Once
you get how the stearing wheel, clutch, gears and brakes work, you can drive
almost any car (until recently, at least..) The QL is more like riding a donkey:
Each one has a mind of its own!
If you know about SMSQ/E, PE, GD2, Q-Liberator, EasyPointer, and FileInfo2, you
probably can skip the manual. You might, however, like to run the boot program
that comes with QV to check if everything you need it there.
For everyone else: You dont have to read this manual, but it may come in handy
if you get stuck!
Requirements and Limitations
============================
QV is designed for fast, GD2-capable, systems with large RAM and plenty of disk
space for files. At present this means QPC2 and SMSQmulator, although it may
very well work on slower systems, provided one adjusts one's ambitions as to the
sizes and types of graphic files - and patience! accordingly.
Note: QV is not designed for displaying your holiday snaps! There are many
limits both in QV, SMSQ/E and the various platforms they run on. QV is designed
to display simple graphics that typically may be found on "QLs" for various
purposes. In QPC2 on a reasonably modern PC a photo of 2048x2048 should work
fine, but beyond that the system starts to creak. So limit your demands to the
platform you use, and use a modern computer for modern file formats and
dimensions!
Toolkit extensions
------------------
As QV is a compiled, PE, SBASIC program, it requires QLib_run or equivalent, and
EasyPtr's ptrmen_cde (V4.10+) pre-loaded to run. Furthermore, QV uses PHGTK by
David Westbury to do its magic.
QV should work on any GD2-capable platform in modes 16, 32, and 33, and display
all the usual QL format files: modes 0, 8, 16, 32, 33, and 64. However,
converting files from one QL format to another requires many different routines
and in some cases conversion tables. So these routines too have been
(optionally) externalised: You can choose only to load those required for a
given platform.
Since some of these toolkits are comparatively large, and since some may also be
used by other graphics-oriented programs, I have provided two different versions
of QV: One with PHGTK and the universal conversion toolkit included, QVtk_obj,
and the other, QV_obj, a minimalist version, without.
However, you still need to load QLib_run & ptrmen_cde. I consider these to be
essential systems extensions without which many modern QL programs will not
work!
If you run the boot script, ..qv_boot, any required toolkits that you dont
already have loaded will be loaded, and the minimalist version of QV will be
fired up if you wish.
Note: However, it cannot always work out which versions of
those toolkits you have loaded, so it may not work in all cases! To be quite
sure, use the versions supplied in ..qv_bin_
Image file types
----------------
The following basic file types can be displayed, although not every variant is
supported:
QL types: scr, pac*, pic, psa, spr.
Non-QL types: bmp, gif, jpg, png, and zxd.
Others may be added later, but QV's "native" file type is the PIC format, in the
same mode as your system display. These are the fastest files to process, so if
you convert the graphics files you wish to use on your QL platform into PICs of
the mode you use for graphics procesing, you'll get the best experience.
* PAC files are RLE-compressed PIC files headed by a 'RLEx' flag.
QV makes this easy for you, as its one main function apart from displaying
files is the ability to save a displayed image, or part image, as a PAC/PIC
file.
Note: Currently the bmp routines are being prepared and only a very basic
version is included. This will only render a small subset of even-Xed, mode 24
bmp images.
Group functions
---------------
The group functions are highly experimental! You should try them out in a safe
setting until you know their limitations. In particular, Cascading and Tiling
many instances of QV is very demanding and may choke the system, locking you
out! If you can think of better ways to do this, Id be glad to hear from you!
Further tweaking, or using an althogether different method, may improve things
in later versions..
Getting started
===============
Updaters should always check the accompanying readme!
Unzip the container file, QVxx_zip to a suitable directory, say win1_utils_view_
EX <prog path>unzip; "-d <temp path>QVxx_zip win1_utils_view_"
Unzip will create a subdirectory under that called qv_ where the QV files will
reside.
Make sure you have QLib_sms or QLib_run loaded (check your boot file, if
necessary). Then Either
1) Add the necessary toolkits to your boot file, reboot, and use QV_obj, or
2) LRUN the ..qv_boot file, or
3) Use QVtk_obj.
However, from here on, both versions will be refered to as QV_obj or simply QV.
On first use you could do worse than run the boot file, eg
LRUN win1_utils_view_qv_boot
This will check (up to a point) whether your system has all the necessary
prerequisits to run QV, and notify you of any missing bits (with the caveats
noted, above!)
Usage
=====
Starting the program
--------------------
QV is command line driven - it has no interface for loading/saving files (and
may never get one). So, to start it you need something like
EX <path>QV_obj; '/F<filename>'
or if there are spaces or forward slashes / in the file name, wrap the filename
in quotes, thus:
EX <path>QV_obj; '/F "<filename>"'
If the filename is the sole string on the command line it does not need to
be preceded by /F or any quotes used as the whole command string is taken
to be the (full) file name of the graphics file to be displayed.
Ideally, youd use it with FileInfo2 so as to execute the graphic file directly
from your favourite file manger. Depending on your system and the program
setting, it may take a little while before the image appears, especially if you
execute more than one at a time!
Further details on how to do that, and how to make QV part of your system, see
below.
Window and display controls
---------------------------
Once you have a graphic loaded, youll see the (more or less) normal Wman
controls. From top left to right:
Resize: HIT to resize the window in the normal way. DO when you are satisfied.
DO the resize button to fit the frame to the image (insofar as
possible). This also resets scaling flag, permitting a new rescaling.
Wake: HIT Wake to pick the "owner" of this instance of QV to the top. If there
is no owner (which is usually the case with this free-standing version
of QV) HITting Wake does nothing.
DOing Wake when multiple instances of QV are active, picks all sister
instances to the top, including any buttonised (Sleeping) ones.
Sister instances are all those instances of QV that have the same
"owner". So if there were different "litters" of sisters, only those
from the same litter would react.
Title bar: HIT, HOLD and DRAG the title bar to move the program window
Sleep HIT Sleep to buttonise the QV window.
DO Sleep to buttonise all sister instances (as explained above) of QV
Exit HIT eXit to quit without sermony.
DO eXit to kill off all sister instances of QV.
Hover over the top of the image, between the Titlebar and the display window to
call up the F3 Command Menu. If you cant wait, click when you see the F3 sprite.
Click on an icon to perform the command. From left to right the commands are as
follows (for an explanation of the what the commands do, see Keystrokes, below):
Tile, Cascade, Info, Save Image, Save Part Image
More on the F3 menu below.
Bottom Right Corner: Move the mouse to the bottom right corner for an
alternative resize feature. HIT and drag the cross bar to the desired
size and DO when youre satified.
This feature, as it stands, is experimental. Let me know what you think:
Should it stay or should I go for something more traditional?
Proportional resize of the window keeping aspect ratio: Press CTRL
while resizing.
Display:
DO on the display to resize the graphic to the size of the frame. And
DO again to revert to the original (full) size.
If the image is larger than the frame, DRAG the graphic around the
display, or use the scroll wheel on the mouse to move the graphic.
Cursor keys +:
CTR, ALT+CTR, SHF+CTRL: Move image inside display 1 pixel at a time
ALT, SHF, ALT+SHF: Move image inside display 10 pixels at a time
ALT+SHF+CTR: Move image inside display to the extremities.
Scroll wheel: Up/Down
Scroll wheel+CTR: Left/Right (QPC2 only)
See note Movement key codes, below!
Errors:
Should a trapable error occur during startup, a small window will
open and display a short error message that hopefully can help
pinpoint the problem. Errors like File not found, graphic not
supported, errors parsing config file or command line, etc, are
usually trapped and displayed this way. The error window
disappears by itself after about three seconds. If that is too
short, simply press a key before the three seconds are up. The
program then pauses until a key is pressed again.
Menu keystroke equivalents
--------------------------
F3 - Calls forth the command menu, with the same options as below.
p, P - * Pin graphic; ie QV instance is temporarily detatched from
group operations. The X-it icon changes to a round exit icon to
indicate the status. HITing a round exit icon changes the pin
status. DOing a round exit icon exits that instance of QV (and
no other).
t, T - Tile - windows of all members of the same QV group (if more than
one) are tiled. If the number of tiles makes that each window
would be smaller than the minimum size, 124x126, QV will just
burp and do nothing.
c, C - Cascade - windows of all members of the same QV group are
cascaded on the screen. The window size is not adjusted, so the
cascade may not look like one if the windows are large..
F1, i, I - Information on the current graphic
DRAG the title bar to move the window.
DO the Info title bar to quit, or press ESC.
If the graphic being displayed is a screen dump, you can
alter the geometry here (see below).
s - Saves the image inside the frame (WYSIWYG) as a PIC file in the
current mode, to source directory (wont overwrite existing, but
adds a number to the end of the file; max 0..9, burp)
S - As above, but saves the full-sized image as a PIC.
r, R - As options s and S above, except saves are done with RLE
compression (but only if more compact, otherwise aborts).
Compressed PIC files like this get the extension _pac
F2 - Calls forth the Transformation menu. (See below)
* Not implemented yet
Transformation keystrokes
-------------------------
Invoked with Control + 0..7
0 - reduce resolution to 4x4 size pixel blocks
1 - flip horizontally
2 - flip vertically
3 - turn upside down (180 degrees)
4 - clockwise by 90 degrees (right)
5 - anti-clockwise 90 degrees (left)
6 - flip top left to bottom right (effectively 1 and 4)
7 - flip top right to bottom left (effectively 1 and 5)
Currently theres an experimental way to do the above via a graphical interface
using the mouse. I dont like it as it is, so it will probably be changed or
removed: Hover the pointer near the middle of the display (hover has been
removed as it was too annoying!) or press F2, to call up the F2 menu. A crude
illustration of possible actions is displayed. Click on one of the numbered
circles to perform the action corresponding to the numbers above. A HIT
somewhere on the display will restore the image to its previous state.
F3 Menu
-------
You can call up the F3 menu at any time by pressing - you guessed it! - F3.
See "Menu keystroke equivalents", above, for details of what each icon or
equivalent keystoke does.
A note on the two save icons: Hold CTRL while clicking one of the save
icons to save the image or part image compressed. If you dont hold CTRL
the image or part image will be saved uncompressed.
Screen Dumps
------------
If a screen dump doesnt look ok you need to manually add the missing
information. Usually it is enough to give the correct mode and let QV work
out the rest for itself. You can however also alter the x or y size if
that seems to be the problem:
Open the Info screen (F3, i) and DO the item you wish to alter and type in
a new value. The other values are recalculated and the graphic is
immediately re-drawn. If you want to keep a given value from being re-
calculated, HIT it to select it. If the values entered dont add up, then
they will be rejected with a rude noise.
Repeat until the graphic displays correctly (if it actually is a screen
dump, that is). You are then advised to save the screen dump as a PIC or
PAC file!
Tip: For regular whole screen dumps of typical sizes, QV is often able to
work out the correct geometry in advance. Regarding part-screen dumps, in
many cases it is enough to specify the mode. At other times and x-dimension
is required in addition, though sometimes the y-dimension works better.
Excuses
=======
As I mentioned, QV is a spin-off from a larger project. This project, QL (or
Quick) PreView - QPV, goes to a lot of trouble to figure out what kind of
graphic file it is dealing with, without bothering the user unless it gets
completely stuck. And once this information is known, it is kept, so it wont
have to bother the user again for the same file it got stuck on last time.
QV has less ability to figure out filetypes, and doesnt keep that information
anywhere, so the relevant information must be provided in other ways.
<rant>The main difficulty in determining filetypes is with headless files, ie
screen dumps. They are an abomination that should never have been allowed! Even
in the day when there was only the simple 512x256 QL there was confusion: Is a
given dump mode 0 or mode 8? (IS it even a screen dump or some other binary?!)
Im sure, given enough time and fortitude, I could produce slighlty better
algorithms to guess at regular and partial screen dumps, but is it really
worth it? Whatever method is chosen, it can never be foolproof.
There is no way to tell with 100% certainty except by the guy in the chair
telling computer what to make of it.
Thanks to the help of some collegues (details below) QV tries to make a guess re
mode 0/8. When it comes to screen dumps with other colour depths, modes, and
sizes, the same problem arises: For example, there is no way (I know of) to tell
whether a given screen dump is in mode 32 or 33.</rant>
QV gets around this in two ways: 1) By file extension and 2) information given
on the command line by the user. The latter takes precedence over the extension,
with any information missing from the command line taken from the extension. If
there are still unknowns left, QV either makes a guess, displays rubbish, gives
up - or perhaps even crashes.
Command Line Options
====================
The options shown reflect the fact that QV is part of something else. The user
is not required to get his head around the internal Types, addresses, etc, used
here. Just focus on the /F, /P and /M, /X and /Y options. In most cases all that
is needed is the /F option, ie the file name. /M, /X, and /Y may be needed for
screen dumps.
/A address (hex) - either /F or /A. /A is only processed if no /F
(Not Implemented [NI] in this version)
/F full filename. If filename contains / or spaces, use quotes
Note: If the ONLY string on the command line is not preceded with a /
option, it is taken to be the file name. Thus EXEP QV; "win1_fred_pic"
should display the file win1_fred_pic (if it exists).
/M mode - Only for screen dumps, otherwise ignored 0, 4, 8, 16,
32, 33, and 64; as in /M33
/N name - Display and job name. The Save name will be
DATAD$ & name$ & n% & '_pic'. Only used with the /A option. (NI)
/O owner ID (8-digit hex) - The ID of the job that "owns" this instance of QV.
(This needn't be the formal owner in the Qdos sense, ie if invoked with EXEC
rather than EX_M/EXEC_W). If the graphic or palette are given as an address
then a genuine /O MUST also be given, otherwise /O is optional (and then need
not even be a job ID). The last four digits will be used as part of QV's job
name.
/P palette 0..3, address (hex) or filename (thb!). If an address, is
supplied and the owner of that memory dies, or an address is given
and no owner supplied, then palette reverts to 0.
/R An alternative root directory can be given on the command line. This
overrides the HOME_DIRECTORY (default) and any root set with (Menu)Config.
/T type code - as in /T9 (see below for details of types and codes).
If /A is used, a type MUST be supplied, If both /F and /T are given, /T is
used, otherwise the filename extension is used. But the actual filetype can
only be guessed at.
Note: If you consistently use other extension names for screen dumps than
sc33, dmp8 etc, you could either alter the program - or use the /T<code>
setting on the command line. /T overrides the extension name.
/X xsize - sizes are in decimal.
/Y ysize - xsize and ysize are only intended for graphics types that dont
contain size information in their header, ie screen dumps. If /X and /Y are
not specified QV will make a simple guess based on the file extension and
size; if they are specified, the given sizes will be used (and if they are
wrong, the program will abort with an error, with any luck).
Note: Normally it will be sufficient to provide only one dimension, ie either
/X or /Y.
Hex addresses may be given as any number (1..8) of hex digits, optionally
preceded by $. Obviously, the address must be valid, although only very
basic checking is done (positive, even).
File Types and Extensions
=========================
In QL-land there are no strict conventions in a lot of areas, not least file
extensions. This is a weakness, to my mind, but its too late to do anything
about it now.. However, when you design programs that require a bit of rigour in
this department, one just has to commit and hope for the best. Below is a list
of file extensions that QV understands. You dont have to use these, but if you
dont use them, you have to supply the relevant information on the command line.
Alternatively, use another graphics viewer!
For completeness' sake, the mentioned file Types are listed too. You can just
ignore them. Supply their values on the command line, to override non-supported
extension names.
Supported "non-native" filetypes are marked with an *
ext code type description
------- ---- ------ ------------------------------------------------
<none> = 00 = gt_unk - no extension: type unknown
bmp = 15 = gt_bmp * PC style BMP files. Many (but not all) kinds
dmp = 04 = gt_scr - Assumed to be mode 0 or 8 screen dump
dmp0 = 05 = gt_sc0 - Assumed to be mode 0 screen dump
dmp8 = 06 = gt_sc8 - Assumed to be mode 8 screen dump
dmp16 = 07 = gt_sc16 - Assumed to be mode 16 screen dump
dmp32 = 08 = gt_sc32 - Assumed to be mode 32 screen dump
dmp33 = 09 = gt_sc33 - Assumed to be mode 33 screen dump
dmp64 = 10 = gt_sc64 - Mode 64 screen dumps. Do they exist?
gif = 13 = gt_gif * Most types of GIF; only first frame shown
jpeg = 11 = gt_jpg * Most common JPEG files (Depends on PHGTK)
jpg = 11 = gt_jpg * Most common JPEG files (Depends on PHGTK)
pac = 16 = gt_pac - RLE-compressed PIC files as below
pcc = 16 = gt_pac - Same as PAC, above
pic = 01 = gt_pic - PIC files, modes 0, 8, 16, 32, 33, 64
png = 12 = gt_png * Most common types of PNG files
psa = 02 = gt_psa - PSA (Part Save Area) files, all modes
sc0 = 05 = gt_sc0 - Assumed to be mode 0 screen dump
sc4 = 05 = gt_sc0 - Assumed to be mode 0 screen dump
sc8 = 06 = gt_sc8 - Assumed to be mode 8 screen dump
sc16 = 07 = gt_sc16 - Assumed to be mode 16 screen dump
sc32 = 08 = gt_sc32 - Assumed to be mode 32 screen dump
sc33 = 09 = gt_sc33 - Assumed to be mode 33 screen dump
sc64 = 10 = gt_sc64 - Assumed to be mode 64 screen dump
scr = 04 = gt_scr - Assumed to be mode 0 or 8 screen dump
scr0 = 05 = gt_sc0 - Assumed to be mode 0 screen dump
scr4 = 05 = gt_sc0 - Assumed to be mode 0 screen dump
scr8 = 06 = gt_sc8 - Assumed to be mode 8 screen dump
scr16 = 07 = gt_sc16 - Assumed to be mode 16 screen dump
scr32 = 08 = gt_sc32 - Assumed to be mode 32 screen dump
scr33 = 09 = gt_sc33 - Assumed to be mode 33 screen dump
scr64 = 10 = gt_sc64 - Assumed to be mode 64 screen dump
spr = 03 = gt_spr - Sprites of modes 0, 8, 16, 32, 33 and 64
zxd = 14 = gt_zxd * Spectrun ZX screen dump
NOTE: Mode 64 screen dumps are not currently supported! (Mode 64 PICs, of
course, are.)
In QPV, "The Project" I keep mentioning, you can add your own aliases, such a
ega, vga, xga, or whatever takes your fancy. If such a move is desirable, it
isnt hard to add it to QV, it merely bulks it up a little and slows it down a
little. But if you find you cant live without, lets discuss it!
Config
======
There is only one (Menu)Config configuration item (see later). The main
configuration is done via a config file, QV_cfg, which must reside in
the Root Directory (see note below!) This is a normal text file that can be
altered in an editor. It may look like this:
QVCFG02
* QV config
winx = 480 -1 => image size, 0 => fullscreen, otherwise given size
winy = 220 if winx = -1, winy is ignored, ie also -1
orgx = -1 -1 => pointer position, -2 => middle of screen
orgy = -1 any other value is as set
scale = full fit => scale to fit window; full => actual size
upscale = no yes => if smaller, follow above; no => dont scale up
fill = $D4D4D0 fill colour (if image smaller than window) $rrggbb
temp = ram8_tmp_ -> temp files (each job gets own subdir -deleted on QV exit)
palette = 2 palette: 0..3 or filename (thb)
asleep = asleep E: asleep D: schlafend, F: dormant, .. (QPAC2 language)
btsleep = Button_Sleep E: & F: Button_Sleep D: Button_Schlaf
wait = 10 Bulk ops: time to wait before giving up in n/50 secs
timeout = 10 Time to hover before F3 menu pops up in n/50 secs
* Movement key codes
fast = 10 pixel step for fast movement
* 3 keys
fastL = 193,196,197 LEFT fast - ALT/SHIFT/ALT+SHIFT + cursor key
fastU = 209,212,213 UP fast
fastR = 201,204,205 RIGHT fast
fastD = 217,220,221 DOWN fast
* 2 keys
slowL = 194,198 LEFT 1 - CTRL/ALT+CTRL or SHIFT+CTRL + cursor
slowU = 210,214 UP 1
slowR = 202,206 RIGHT 1
slowD = 218,222 DOWN 1
* 1 key
maxL = 199 LEFT max - ALT+SHIFT+CTRL + cursor key
maxU = 215 UP max
maxR = 207 RIGHT max
maxD = 223 DOWN max
Initially, there should be no need to change anything. If the meaning of any of
the settings is unclear, try them out, one at a time! The config file is read
each time an instance of QV is started.
Now for the nitty-gritty:
The first item in the file is the ID. It MUST be first and it MUST be the only
thing on the line.
Any line starting with an asterisk * is ignored. Useful for comments or trying
things out. Each setting consists of a name (which must not be altered) followed
by an equals sign = followed by the settings value, thus:
setting = value [optional remark]
Values may not contain spaces!
All keys must be present and in the order shown above!
The following settings are defined in this version of QV:
winx - this is the display window's startup x-size in pixels. It can be
any reasonable size that can be displayed on your screen,
eg 480. Minimum 124.
It can also be a key:
-1 => the window should start up in the size of the image
0 => the window should start up in full screen mode (not
yet implemented (and may never be)).
Note: If winx is set to a key rather than a fixed value, then winy
(see below) is assumed to be the same and is ignored.
winy - this is the display window's startup y-size in pixels.
Minimum size 126
orgx - Display screen origen: Here you can set either a fixed x-origen or a
key:
-1 => current pointer position (wherever that may happen to be
at the time of invocation.)
-2 => centered (horizontally) on the screen
orgy - Similar to orgx. Keys for orgx and orgy are interpreted
seperately, so you could have QV start up at a fixed
y-position, but centred horizontally - or vice versa.
scale - This can be set to "fit" or "full"
fit => scale the image to fit the window size specified above
Note: This will delay the time taken before the image is
displayed, depending on the speed of your system!
full => display the image full size within the specified window
If winx is set to -1, the image will be displayed in
full (within the limitations of your screen).
upscale - This can be set to "yes" or "no"
If yes, and scale is set to "fit" images smaller than the window
size will be magnified to fit the size specified.
If no, images smaller than the window will be shown at their
actual size, even if scale is set to "fit".
fill - Here you can set a 24bit RGB "paper" colour, that fills the part of
the window that is not covered by the image.
You specify the value as hex, optionally preceded by a dollar $ sign.
temp - Here you specify the path of a temporary directory. This is used
for conversion of foreign gfx formats (jpg, gif, etc) and for
scaling. See note, below.
palette - Here you set the application's palette. You can specify either a
system palette: 0..3, or the filename of a binary theme file
(extension thb). More info on Themes and Palettes under the
Troubleshooting section below.
asleep - Set the name of the asleep job name tag according to the language of
your version of Qpac2. For English it is "asleep", for German
"schlafend", for French "dormant". More info under Troubleshooting,
below.
btsleep - Here you set the name of the Button_Sleep Thing according to your
Qpac2 language. In English and French it is "Button_Sleep", in German
"Button_Schlaf". See the Troubleshooting section for more details.
wait - How many ticks to wait for a QV instance to complete its bulk op
before giving up. At present this doesnt work as intended, but if you
have problems with the scheduler gagging on all the ops, you could try
increasing this number. (Also, you could try using fewer instances of
QV simultaneously!)
timeout - The number of frames to delay before the F2/F3 command menus appear.
-1 => Dont pop up, ie you need to click the line or press the funtion
key for the menu to show. Otherwise 0..whatever, default 10 = 1/5s
(1/6s, US)
Movement key codes
------------------
Different platforms support different key codes for the scroll wheel, for
example, and some emulator hosts dont allow access to all SMSQ/E key
combinations. Finally, some people prefer the contents to scroll within
the frame, while others prefer the frame to scroll around the contents. So
now you can configure this to suit your tastes and the various host
platforms. Its a fiddly business, but you should only need to do this
once, or at most a few times, or better still: not at all.
Update: The scroll wheel now appears to work in the same way on
all(?) systems with SMSQ/E V3.38+. (At least on QPC2 and SMSQmulator
under Windows, and on Q68.)
There are three groups of movement key codes: Fast, slow, and max. You can
also define the step size for the fast group; default: 10 pixels a pop.
The fast group has three key codes for each direction, nominally:
ALT+<cursor>, SHIFT+<cursor>, ALT+SHIFT+<cursor>
The mouse scroll wheel normally falls into this category
The slow group moves the gfx or frame 1 pixel at a time in the direction
of the chosen cursor key:
CTRL+<cursor>, ALT+CTRL+<cursor> or SHIFT+CTRL+<cursor>
The final group moves the gfx/frame to the extremities:
ALT+SHIFT+CTRL+<cursor>
To configure these settings, select the key combinations you require,
determin their key code, and write those codes into the config file, and
save it. (You may first want to make a copy of the original!)
Each group and direction should only have the number of key codes as
described above. If you need to eliminate a key combination, then simply
repeat one of the other codes from the same group and direction. Dont use
any other code, as this could confuse QV! Codes are separated by a comma.
NB: No spaces allowed!
Selecting a suitable temp drive
-------------------------------
Converting a jpg image to the native QL format, PIC, can use a lot of space,
usually a multiple of the original foreign image size. If the image is scaled,
both the converted image and the scaled image are kept on the temp drive while
QV runs. These files are normally deleted on exiting the program. Each instance
of QV will have such files in their own subdirectory in temp.
Pic files of the current display mode dont need conversion, so use less space.
Only a scaled pic will eat up additional space. (Of course, in addition, the
file being displayed also takes up RAM.)
If you have plenty of memory, you could keep temp on a dynamic ram disk. That is
fast and flexible, and guarantees a fresh and clean start on next boot up.
If memory is tight, it is better to specify temp on a hard drive, eg win3_tmp_
or win1_qv_tmp_ (QV will create the ..tmp_ part of the subdirectory itself.)
Each instance will also create a subdirectory below that. These subdirectories
will be deleted on termination, but the ..tmp_ directory will remain.
If QV is terminated in an unexpected way, eg with RJOB, a job killer program,
or by resetting your machine with instances of QV still running, it will not be
able to clean up its mess, and the number of orphaned temp files may grow to
fill up the disk. So if you use a non-volatile storage medium for temp, and
habitually kill off QVs without exiting them properly, you should check temp
every now and again and remove any residual temporary files. Or better still,
add a routine to your boot file to automatically delete the contents of tmp
every time you boot up.
Ive included one you can use: DelDir_bas. Simply add the line
ERT DelDir(#0; "<devN_>", "<dir_tmp>", 1)
somewhere in your (secondary) boot file, and append the S*BASIC DelDir function
to the end of it. <devN_> should be the name of the device you configured in the
QV_cfg file to be your temp device, and the dir_ part of <dir_tmp> any
subdirectory prior to tmp. Thus if you wanted temp to be in win1_qv_ youd put
ERT DelDir(#0; "win1_", "qv_tmp", 1)
DelDir will then delete the contents (if any) of win1_qv_tmp_ on each start up.
A note about Root
-----------------
The root directory has one main function: It points to the location of the
configuration file, QV_cfg. In normal use this will be the directory from which
QV is executed, ie the HOME_DIRECTORY. Not all programs and system extensions
recognise the home directory, so in such cases you need to tell QV where to find
its config file. This can either be done permanently using the standadrd Qdos
configuration utility, Config or JMS's MenuConfig, as described elsewhere in
this document, or by supplying the name on the command line using the /R option
(see Command Line Options, above).
The /R option has the added advantage that you can have different config files
for different purposes, provided you keep them in different locations.
Making QV part of your System
=============================
Unless you know youll only ever load one or two graphics at the same time every
blue moon, it makes sense to load QV residentially as a Thing. This has two
great advantages: It saves a lot of memory, as however many instances you have
running, it uses only a single copy of the code! Secondly, QV should start a
little quicker. The disadvantages are that the program occupies memory even when
it is not used, and it adds a moment to your boot time. A compromise is to use
HOT_LOAD, or manually load it as a Thing only when you are going to be using it
a lot.
If you load QV as a Thing with HOT_RES & co, you will need to configure the
program with (Menu)Config first! There is only one configuration item: "Root
directory". Here you should set the location where the QV_cfg file can be found;
not the full filename, only the directory, terminated with an underscore.
To make QV a resident Thing, as described, you could do the following:
er = HOT_REMV(CHR$(0)): REMark Remove previous key assignment, if any
ERT HOT_RES(CHR$(0), "<path>QV_obj", "QV")
It doesnt make sense to put QV on a Hotkey as such, as the only way to make it
display a graphic is to instruct it via the command line. Therefore an
impossible-to-type key, CHR$(0), code is suggested. You can check whether the
Thing is locked and loaded by checking the Thing list.
Now you can display a graphic with:
EXEP QV; '<filename>'
Better still, also add QV to FileInfo2! That enables you to view a graphic by
simply executing the file from your favourite file manager.
Assuming you have FileInfo2 and know how to use it, here is a list of steps you
need to take to add an extension, JPEG's jpg, in this example:
1. Fire up the FI2 user interface
2. If you dont already have an entry for jpg, add it now.
3. If you already have an entry for jpg, add a new action View, or QView, ..
4. Skip to "Thing to launch", and make sure it is highlighted
5. Add QV in the box below (if you followed the HOT_RES example above).
6. Next, in the box for "Exeutable file to load" enter the full name and
location of the QV_obj executable (especially if you didnt Thingify QV)
7. On the line below that, select the "Put it on job stack" option
8. Enter the command line dialogue and enter /F" (optional if only parameter)
9. Add <<devN_name_ext>> by selecting it, and terminate with a "
The line should look like: /F"«devN_name_ext»" (or «devN_name_ext»)
10. Click on the Adopt the setting icon, and then try it out
Similar steps should be taken for each of the foreign graphics types, png, bmp,
etc, and ditto for pic, pac and psa.
Now lets try the scr extension, as this is a little different. In step 9.,
after the final closing quote, add /X512 /Y256. QV will try to figure out
whether the screen is mode 0 or mode 8. If you know your screens always will
be mode 0, you can add that information: /M0, otherwise leave it blank. Of
course, if you have screen dumps that are only part of a screen, this may not
work. To view such a file you may have to revert to a manual EXEP 'QV'; etc,
using what information you have and provide that on the command line. If you
use the extensions suggested above for screen dumps, QV should normally be
able to work something out.
Once you are satisfied, click the "Adopt these settings?" followed by "Save a
configured copy?" and confirm and save.
Troubleshooting
===============
System crash
------------
On loading some large files the system may crash spectacularly with no error
message!
Early versions of QPC2 (pre V4.95) and current versions of SMSQmulator
(V2.29) have this tendency. Correct me if Im wrong, but this is down to
some issue with the emulators. As I dont know what their limits are, and
as they are liable to change at any time, I cannot protect against it. a
2048x2048 PIC crashed QPC2. I notified the author and it was fixed. a
1600x1200 SCR crashed SMSQmulator (but not a 1600x1024 one). I only just
found out and will inform, so this could be fixed in later versions by the
time you read this.
Qlib errors
-----------
If you get a variety of Qlib errors, eg "at line xxxx PTOP <error message>",
etc.
First try running the boot program (..qv_boot). If this does not resolve the
problem or tell you what QV objects to, try loading the latest ptrmen_cde:
LRESPR <qv_path>bin_ptrmen_cde
There is no easy way to tell which version of ptrmen_cde is loaded, so its
simplest just to load the latest version on top of whats there and see if that
solves the problem. You need to do this in Job #0, ie your main system console.
It may be best to close down any programs currently using ptrmen when you do
this.
Cannot find QV_cfg
------------------
If you have set QV up as a Thing with HOT_xxx (other than HOT_LOAD) you need to
configure QV with (Menu)Config to tell it where to find its config files.
Alternatively supply the location of QV_cfg on the command line with
/R<directory>.
The error window doesnt go away
-------------------------------
The program error message window disappears automatically after about
three seconds. No need to acknowledge. If you do acknowledge, however, you
have to press a key again for it to go away.
Supported foreign format graphic doesnt display
-----------------------------------------------
If you cannot get a non-native file to display (error Not Implemented), you can
try loading it into some graphics program on your PC, such as Windows Paint,
resave it (just click the Save icon) or use Save As.. to save it in a
supported format, and then try again. Or perhaps use a different graphics file
viewer for these files, not based on PHGTK/Photon.
Some very large images wont load. They may return the error Medium is Full.
Remember a jpeg can be orders of magnitude larger than the stated file size once
its uncompressed. If a RAM disk is used as your temp drive, twice that amount of
memory is required. If you have specified a hard disk as your temp file: Is
there enough room on it to contain the uncompressed file?
Is the temp directory is full of orphan files? Shut down all instances of QV
and then delete those files! Add DelDir_bas to your boot file (see "Selecting a
suitable temp drive", above).
Some very large images wont load however much available memory you have. I dont
know why, or what the exact limit is. The best way to resolve this is to reduce
their size in some convenient PC image editing program, or avoid them altogether
in the QL environment.
All files show as Not Implemented (even when they shouldnt)
-----------------------------------------------------------
Did you remember to use the /F key before the file name? For screen dumps you
may need to add more parameters, eg mode and/or size.
Screen dump issues
------------------
Screen dumps are tricky, as they dont carry the necessary information on the
data they contain. So some guesswork is required, and this may sometimes be
wrong.
Use the /X and/or /Y parameters to determin the dimensions, or try the /M(ode)
parameter. Of course, these are but ad hoc solutions, and may not be suitable
for FileInfo2.
If you consistently use other extension names for screen dumps than sc33, dmp8
etc, you could either alter the program - or use the /T(ype code) setting on the
command line. /T overrides the extension name.
Screen dumps dont currently compress (R and r option). Save them first as
PICs (S and s options), reload them and then save compressed.
Theme, Palette, thb files
-------------------------
thb - refers to the binary version of the Theme files, ie the palette of colours
that are used for the program display furniture. There are more details of this
on Knoware/Pointer/Themes.
Sleep, asleep, btsleep
----------------------
asleep and btsleep - For the Sleep functions to work, you need to ensure that
these settings reflect the language used by your version of Qpac2. You could
look at the binary, if you dont know, or start an SBASIC daughter job and try:
EXEP Button_sleep
If the program window gets buttonised, ie "goes to sleep" then check the jobs
list: If theres a job called SBASIC asleep, then your Qpac2 language is English,
so do nothing. Otherwise it is either German or French, in which case you must
change the setting in the config file accordingly. If the SBASIC job does not go
to sleep, you probably have a German Qpac2. Try
EXEP Button_Schlaf
If that works, your Qpac2 language is German and you need to change both
settings accordingly.
Blurred graphics
----------------
The current version of QV doesnt try very hard to ensure that when it resizes a
graphic it gets the best possible results. This requires research and testing.
It may be improved in a later version.. (Or perhaps youd like to fix it
yourself, or offer advice on how to do it?) In the meantime, where this is
important, try some other graphics manipulation program, such as SQRview or
QTImage and see if you get a better result.
Graphics wont move in the window. Graphic wont resize
-----------------------------------------------------
Sometimes the program seems not to react to scaling or moving. This is due to a
temporary workaround to avoid the opposite: overactive moving/scaling. Hopefully
a better method may be found so it can be fixed. The solution is to move the
pointer out of the window briefly, and then try again.
Group functions dont work properly
----------------------------------
Well, this is entirely experimental at present. It may improve with some
tweaking and tuning, or it may require a different approach altogether. On the
other hand, it may never work as the "QL" wasnt designed for this kind of thing.
Then again, SMSQ/XE (V5+), expected in around 2050, could be the solution..
In the mean time, it may help to adjust the 'wait' parameter in the config file.
Sometimes laggardly windows may fall into place if you re-issue a tile or
cascade request on a different window.
Squashed images
---------------
QL and QL-like hardware (and perhaps the Q-emulator emulator) all have
non-square pixels. This results in images that look normal on an emulated
platforms appear somewhat squashed on QL hardware - and vice versa. There
may be software out there that corrects for this. QV doesnt. Sorry.
Acknowledgements:
=================
As is often the way of things, nothing here would have been possible without the
work of others! SMSQ/E, QPC2, SMSQmulator, Q-Liberator, etc, are by now well
known quanties, so I shant delve into the detail here. My thanks to all those
who made them possible!
Specifically, for this program, special thanks are due to David Westbury for the
excellent PHGTK graphics conversion toolkit which forms the core of QV, and
which was the spark that set off this whole project.
Thanks are also due to Dilwyn Jones for his Guess toolkit - to guess whether a
QL mode screen dump is in mode 0 or 8. Both he and Bob Spelten will be thanked
again in a future iteration of QV as their BMP2PIC routines will (hopeflully)
be incorporated as well to complete the planned suit of foreign format
conversion capabilities.
Thanks to Wolfgang Lenerz: I have temporarily borrowed one of his very early
BMPCVT toolkit to fill in the gap while Bob and Dilwyn's comprehensive toolkit
is being prepared to fit the QV paradigm.
I have included the currently latest version of EasyPointer's ptrmen_cde,
copyright Albin Hessler and Marcel Kilgus. I hope this is in order. The full
EasyPointer suit may be found at Marcel's excellent website
http://www.kilgus.net/qpc/. Check it out!
Regarding the internal SMSQ/E conversion routines, a few of which Ive
shamelessly nicked from the SMSQ/E sources, it is sometimes hard to tell who
authored them: Tony Tebby, Marcel or Wolfgang - or anyone else. Many thanks and
kudos to them!
If I have forgotten anyone, I apologise. It will be rectified as soon as Im
informed.
Program status:
===============
The program, QuickView (QV) and all its associated source files, toolkits and
other files authored by me are subject to the Conditions of use and DISCLAIMER
as per Knoware.no. They are copyright pjw, 2020
The remainder are subject to the licenses, conditions and disclaimers of their
respective authors.
pjwitte, 2020 Dec 09
Revised, pjw, 2023 Apr 25
Conditions of use and DISCLAIMER as per Knoware.no
QL Software