Fsel

Note: Earlier versions of FSEL (pre V10) were included with various programs. The command line options of FSEL have evolved meantime, but I havent updated older programs in line with FSEL. You are advised to continue using the FSEL that came with your other program. However, if you use my Snip program, V03 or earlier, you should replace its FSEL with V11 or later! Any other program using FSEL V10 or later can also use the current version (V12+).
                                    FSEL
                                    ====

       FSEL is a simple wrapper for the Qmenu FILE_SELECT utility
                        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 don't
require a 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 don't 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 mentioned above, although it is built
into SMSQ/E. I've 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 address, ie a memory address in
which to place the selected file name, you must ensure that the memory does
not become unreserved - or catastrophe 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 parameter 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  (approx)
        /H - height in absolute 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!) A minimum 44 bytes of buffer
             required for return

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

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$(retadd + 2, l%)
        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". (Most of that functionality has been removed as these are
avoidable programmer errors.)


Thing
-----

FSEL can also be used as a Thing, eg

        ERT HOT_CHP1("f", '<path>FSEL_obj', 'FSEL')

or you could add some parameters:

        ERT HOT_CHP1("f", '<path>FSEL_obj'; '/Dwin1_prg_ /E_bas /P2',
        'FSEL')

Invoke it by using the Hotkey from the keyboard or with EXEP or FEP() from
within your program..


Software status
---------------

V0.12, pjw, 2021 Nov 09 (This text and the boot file edited 2022 May 07)

Qmenu is © JMS, it can be found at Marcel's super web site:
www.kilgus.net/smsqe/

The remaining code, including the toolkit commands, are
© pjw, 2021 Nov 09, unless otherwise stated.

The S*BASIC source code is included with this distribution; the source code
for the various toolkit commands can be found at
www.knoware.no/htm/toolkits.htm

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

               Conditions of use and DISCLAIMER as per Knoware.no
<-Back
ToP