FSEL
                                     ====

       FSEL is a simple wrapper for the Qmenu FILE_SELECT utiltiy
                          for Qdos, Minerva & SMSQ/E


FSEL allows you use JMS' excellent FILE_SELECT utility as an external
program. Ideal for use with applets and programs that otherwise dont
require window large enough to display the FILE_SELECT window. Simply call
up FSEL at some convenient position relative to your program's display.

You could also add it to a hotkey, to use it as a tool to quickly look up
and fetch a filename, without firing up a file manager.

Note: This version of FSEL (0.10+) is incompatible with all previous
versions. Old software using old versions will still work with the old
versions, but not the new, so dont replace them unless you replace the
software using them!


Requirements
------------
FSEL requires a reasonably up to date version of Qmenu (not included, but
most QLers have a copy somewhere). Qmenu also requires the Pointer
Environment, so if youre using Qdos/Minerva, ptr_gen (V2.06+) and wman
(V2.08+) must be loaded. SMSQ/E has these built in. In addition, FSEL uses
the stuffer buffer (or rather FILE_SELECT$ does). This can be had in
Qdos/Minerva by loading hot_rext (V2.31+).

This may seem like a lot of extra baggage, but ptr_gen, wman and hot_rext
are, in fact, just the Extended Environment - ie the basic GUI system for
the QL.

Another requirement for Qmenu is OUTLN. Strangely, this command is not
included in any of the components mentione above, although it is built into
SMSQ/E. Ive included a single keyword toolkit here, which you can LRESPR if
you need to. It is also included with Qptr. A similar command is available
with EasyPtr's ptrmen_cde toolkit. However, there it is called OUTL, so you
cant use it here without altering FSEL.

You can use the supplied boot program to check for, and if necessary, load
OUTLN.

The source code is written for SBASIC, but should run under SuperBASIC
after some minor tweaks.


Usage:
------
There a small demo program, Harness_bas, that shows how FSEL could be
used. It is only an example, but demonstrates some core principles: One of
those is that if you supply FSEL with a return addess, ie a memory address
in which to place the selected file name, you must ensure that the memory
does not become unreserved - or catastrophy could ensue! The best way to
ensure that is to invoke FSEL with EX_M or FEX_M. Failing that the much
less convenient EW or FEW could be used. Failing that, you should avoid
using a return address and only use the stuffer buffer. (F)EX_M is part of
SMSQ/E V3.22+ and TK2 V3.20+

To control FSEL you pass parameters to it via the command line, ie

        id = FEX_M(<fsel>; <command_line>)

Each command is a slash, /, followed by a key, followed by the parameter.
(See Harness_bas for examples). If the prameter contains spaces or slashes
it should be quoted, eg /T"This is a title string"

These are the commands FSEL accepts:

        X - x-origen of applet in absolute pixels
        Y - y-origen of applet in absolute pixels
        W - width in absolute pixels
        H - height in lines of 12 pixels approx
        T - title - a quoted or unquoted string
        D - name of directory
        F - file name - the full file name
        E - extension - the file names will be filtered by this
        P - palette: System 0..3 or address of private palette (in hex!)
        R - return address (in hex!) 44 bytes required for return

The result of the selection is always returned in the stuffer buffer
(normally accessed with ALT + SPACE).

If a return address is supplied, the selection is also put there and can
be extracted by:
        retadd = ALCHP(44)

        <do FSEL with /R <$retadd>>

        l% = PEEK_W(retadd)
        fnm$ = PEEK$(l%, retadd + 2)
        RECHP retadr

Normally, there should never be any errors, but if you are having a
problem with parameters, an error code may be returned at that same
location, as a string, eg "-15".


Software status
---------------
Qmenu is ©JMS, it can be found at Marcel's super website:
www.kilgus.net/smsqe/

The remaining code, including the toolkit commands, are
©pjw, 2019 Jul 26, unless otherwise stated.

The S*BASIC source code is included with this distribution; the source
code for the various toolkit commands can be found here.

The OUTLN command is basically a copy taken from the SMSQ/E sources,
© Tony Tebby

Conditions of use and DISCLAIMER as per Knoware.no

pjw, 2019 Jul 26