PickQD
                                    ======

                         Manage multiple copies of QD

Blurb
=====

You may have experienced that you have so many copies of QD running that you
cant (quickly) find the one you want. So it would perhaps be nice to have a
list of which ones are running so you can pick that to the top of the pile
without having to cycle through the whole lot. Or perhaps its better to
button them out of the way - or just shut the whole lot down?

PickQD could be the solutions to your problem!


Index
=====

        Requirements
        Getting started
                Configuration
        In use
        Troubleshooting
        Software status


Requirements
============

PickQD requires JMS'es Qmenu to run. It also requires SMSQ/E V3.35 or later
(for the FDEL command - or use my compatibility toolkit, available on
Knoware.no). FSEL, the floating FILE_SELECT$ wrapper is also required and is
included with this package. The compiled version, PickQD_obj, needs Qlib_run
or equivalent. If you decide to use PickQD uncompiled (not recommended except
for testing or development) you need to load the included toolkit PickQD_bin.

Since PickQD originated on Qdos, it shouldnt be too hard to re-engineer it
for Qdos again - the source code is included! However, please dont grumble
if PickQD doesnt work very well on QL hardware in high colour mode. These
systems are just too slow to do it justice. In QL colour mode, it may still
work ok, though.


* * * * * * * * * * * * * * *   NOTE and BEWARE!  * * * * * * * * * * * * * * *
*                                                                             *
*  PickQD works by stuffing the keyboard queue with the characters you would  *
*  normally type at the keyboard. However, it does this automatically with    *
*  very little awareness of the effect of its actions. So, it could,          *
*  potentially get in a muddle, especially if there are other things going on *
*  in the machine - like you moving your mouse rapidly around while PickQD is *
*  working - or even activities of the host platform in the case of           *
*  emulators. This could cause a problem particularly with the                *
*  Save and Shutdown option!                                                  *
*                                                                             *
*  Another danger with unsupervised saving is that one may inadvertently      *
*  have entered spurious characters into a file and these get saved without   *
*  one noticing. They can be hard to find later - unless something goes       *
*  wrong!                                                                     *
*                                                                             *
*  PickQD started life as a "quick hack". However, I have spent some time     *
*  recently to try to make it more safe. Options 0 to 3 are pretty safe.      *
*  Option 4 - Save and Shutdown is by its very nature inherently "unsafe".    *
*  Also I have not been able to test every possible combination of actions or *
*  environments a user might subject it to. The decision to Use or not to Use *
*  is entirely yours - as are the consequences.                               *
*                                                                             *
*  You could, of course try to improve PickQD: you have the source code! (And *
*  then Id like to have a copy!)                                              *                                                    *
*                                                                             *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


Getting started
===============

PickQD expects QD to be loaded as a Thing. You do that by, for example, doing a

        LRESPR <path>QD

in your boot file and then adding the Hotkeys you require to invoke or pick QD.

FSEL can optionally be loaded as a Thing in your boot file, eg do a

        ERT HOT_RES1("F", '<path>FSEL_obj'; '/P2', 'FSEL')

PickQD could be invoked with:

        EX <path>PickQD_obj[ ; <alt home directory> ]

however, it is designed to be invoked via a Hotkey.

I use the following Hotkey set for QD and PickQD. You can, of course, use
key combinations of your own choice:

        cml$ = '\dwin1_prg_ \e_bas \h<path>bas_ \tQBasic \c100 \n68'
        ERT HOT_THING(CHR$(17), 'QD'; cml$
        ERT HOT_WAKE(";", 'QD')
        ..
        ERT HOT_RES1(':', "<path>PickQD_obj"; 'dev2_', 'PickQD')

where <path> is some location, not necessarily the same one. CHR$(17) is
CTRL + ';'

Additionally, after the above, you could put it on a button:

        BT_HOTKEY 'PickQD','PickQD',,, 1

Just click on the button to invoke PickQD.

Note: Control characters dont work well on SMSQmulator, so the CHR$(17) line
only works for QPC2, Q68, Qx0, etc. However, there are so many different other
ways to start QD that I hadnt noticed for many years!

What this means is that ALT + ';' cycles through all the different instances
of QD running on the machine, while ALT + SHIFT + ';' fires up PickQD to
manage them. ALT + CTRL + ';' starts an instance of QD ready for writing a
BASIC program. Among other things (see the QD manual!) it tells QD where to
find the BASIC help files, and it configures QD to use the QBasic Thing. (On
SMSQ/E I now much prefer to use the SBAS/QD Thing.)

The reason I use dev2_ as the location for the PickQD configuration file
is that dev2_ points to a different place on each platform, so each platform
can have a different configuration file best tuned to its capabilities.
That also means that I can use identical disks on each platform and not
have to fiddle with maintaining separate backups, boot files, etc, for
each: Whichever platform Im working on, its always my "Home QL".


Configuration
-------------

There is a small and primitive configuration file that needs to be attended
to first. Its called PickQD_cfg. Its a plain text file consisting of
a few entries, each on their own line. The location of this file is
expected to be found in the Home Directory. However, if a different
location is provided on the command line, then this is used instead. In
fact, if you load PickQD as a Thing, the location of the PickQD_cfg file
HAS to be supplied on the command line as Hot Things dont know about the Home
Directory yet.

Note that if the file cant be found youll get a Not Found error dialog as
the first thing when you try to start PickQD.

Heres a sample config file. Everything behind and including | is comment
for the purposes of illustration. No comments are allowed in the actual
file:

win1_util_file_Fsel_obj                   | Fsel_obj or <path>Fsel_obj
10                                        | Breathers in 1/50th second
asleep                                    | Sleep thing job name appendix
QD NO NAME                                | Unsaved QD document name
QD row/column                             | QD help job name
* \n80 \c80                               | Fallback command line for QD
txt \n80 \c80                             | Text file command line for QD
bas \n80 \c100 \hwin2_hlp_bas_ \tSBAS/QD  | Basic source file command line
asm \n80 \c100 \hwin2_hlp_asm_            | Assembler command line for QD

Here is the nitty-gritty:

1. On the first line supply the full name and location of the FSEL utility.
   If only the text 'Fsel_obj' is entered then the current directoy is used.
   FSEL needs to be V10 or later. (Included with the package.) If youve
   loaded FSEL as a Thing, this information is ignored, as PickQD will try
   the FSEL Thing first.

2. The timeout delay. You may need to try out different values here
   depending on your system. Values between 5 and 20 are reasonable. This
   is particularly important for the Shut down and Save option (Note the
   warning above!)

3. The next line is for the name of the Sleep Thing, either 'asleep',
   'schlafend', or 'dormant', depending on your Qpac2 language. This is
   only meaningful if you should happen to use the Sleep Thing to put your
   QD to sleep (buttonise it). Normally QD does its own thing when it
   buttonises, so if you always use that - or dont know what Im talking
   about - you should be alright!

4 & 5 QD comes, as far as I know, only in two language flavours, German and
   English. However, there may be more.. Some tests inside PickQD need the
   correct language to work. So on these two lines you need to enter the
   No Name designation your QD uses, followed by the row column job name,
   thus either:

   QD NO NAME
   QD row/column

   or:

   QD OHNE NAMEN
   QD Zeile/Spalte

   You can find these texts by starting up the version of QD that you
   normally use with a blank document. Now list the Jobs in your system to
   see what QD's job name is and what its row/column job is called in your
   language and enter the names exactly as you see them, including the
   leading 'QD '.

6. The next lines represent the command lines given to a new instance of QD
   depending on the kind of file you are loading. You may need to check the
   QD manual for details of the available options.

   You can have as many lines as you like, but only one for each extension.
   Each line starts with an extension name, eg txt, bas, link, .. followed by
   a space, followed by the command line you wish to give QD for that
   extension.

   The first of these lines starts with an asterisk. This line is the fallback
   command line that will be used for all instances for which no extension
   has been defined.

   Extensions can be up to 6 characters long, and the commad line itself
   can be up to 120 characters long. Anything beyond these values will be
   truncated! So if you exceed them you will not get the results you
   expected. (You can, of course, alter the code and re-compile if you
   really need to!)

   PickQD always prepends the following to the command line, so you should
   not add these again: \f <filename> \d <directory>


In use
======

You may need to "tune" PickQD to your particular platform(s). First try
buttonising and unbuttonising a bunch of files. See to it that all files are
processed. Reduce the "breather" time (see Configuration) until you
see files being missed out, then increase the time back up again. Shutting
down, especially with save may require longer breathers even though QD
operates autonomously once the command has been accepted, as the machine
will be busy with the file operation.

PickQD has, at present, four commands:

        0 - New QD -
        1 - Buttonise QDs -
        2 - Unbutton QDs -
        3 - ShutDown No Save -
        4 - ShutDown & Save -

You invoke the command either by clicking on it or pressing its number

0 New QD

        Fires up FSEL so you can select a file to load. Alternatively you
        can manually enter a file name here of an existing or a new file.
        If the file doesnt exist, this will be its name, otherwise it will
        load the existing file.

        If no instances of QD are running, FSEL is the first thing youll
        see, not the standard menu.

1 Buttonise QDs

        This causes all running instances of QD to be buttonised

2 Unbutton QDs

        This wakes all buttonised instances of QD

3 ShutDown No Save

        This shuts down all running instances of QD that dont contain
        unsaved data.

4 ShutDown & Save

        This shuts down all running instances of QD. If any are flagged as
        changed (and only then) the file is first saved, overwriting any
        previous version. Then the instance of QD is shut down. (QD can be
        configured to backup a previous version of a file on saving. Check
        out the QD manual!)

        If two or more instances have the same file name NEITHER of them are
        saved nor shut down! (You may inadvertently have altered and/or
        saved, both/either file, so you have to decide manually what to do
        with them.)

        If instances of unsaved files havent been given a file name yet,
        they will be also not be shut down.

               See warning note at the top of this document!

The remaining items on the list are the file names of the running instances
of QD. Click any of those or type their leading number/letter to pick that
instance to the top - even if it is sleeping/buttonised.


Troubleshooting
===============

If you load a whole bunch of QDs at once, for example via Qpac2 and
FileInfo2, or by some other automated process, QD wont have time to set
the job name for each of those files! (Thats a QD "issue", not a PickQD
one). So you get lots of jobs called QD - and nothing else. PickQD tries
to give these jobs a second chance to set a name, so they all get picked to
the top of the pile on the first occasion PickQD is invoked after such a
mass execution(!) event.

If you have a large number of QDs running at once and want to process them
all (buttonise, shut down, etc) some may get left behind. Consider
changing the breather (second line in PickQD_cfg). Either add on a few
ticks, or reduce by a few ticks (slower is not always better!) You may never
hit a perfect sweet spot, as there are so many external variables. But once
youve found a "comfortable" value, stick with it. And you can always re-run
the shut down or other process a couple of times.. Occasionally you have to
flush a toilet more than once: Once for the bulk and a few more times for
the residue!

Sometimes, of course, a recalcitrant QD wont go away. You may find, if
you have configured QD to have a solid Changed File indicator rather than
that annoying blinking one, that it is stuck in the off position although
the file has actually changed. Just do a CTRL + 'x' in the offending QD to
confirm whether it was a glitch or whether PickQD just saved your ass!

(Apologies for the toilet jokes. Its been a long day..)

Two instances of QD with the same file name cannot be shut down with the
save option - even if neither file is in the "unchanged" state. This is a
safety feature.


Software status
===============

This software is free for you to use and distribute without payment,
provided the original author is acknowledged.

Toolkit source code available at Knoware.no

Conditions and DISCALIMER as per Knoware.no

V0.07, pjw, 2021 Nov 19