The QL Toolbox '98 Collection
-----------------------------

TypeInFile - Type Text Files into other Applications
----------------------------------------------------
This tool is designed to "type in" the contents of a text file into another
program, as if the user had typed them in. It can be used for a variety of
purposes, including composing E-Mails off-line and then typing them into
your favourite comms package (mine is QTPI), inserting fragments of code
into both primary and secondary (Minerva, SMSQ) S*BASIC Interpreters, and
pasting the Scrap into edistors that don't support it.

TypeInFile requires (of course) the Pointer Environment, or SMSQ, to be
loaded, as well as Jochen Merz's Menu Extension.

When the program is started, you will be presented with a fairly standard
user interface that is very similar to my other utilities. The main
difference with TypeInFile is that it does not have the characteristic
"Output Window" filling the bottom two thirds of the screen. Instead, it's
just blank screen there. The reason for this waste of screen space is that
I have yet to find a reliable method to start a FILE_SELECT$() dialog that
is larger than the owning job's primary window. (In fact, for my own use, I
have created a job called FSel which is loaded as an Executable Thing and
acts as a command-line interface to FILE_SELECT)

Running through the items on the screen, this is what you will find (I
won't cover the stuff that's always in the menu bar: Move, Info, Quit, and
Sleep) ...

Source
------
Select the name of the file that you want to type in. A DO on the label or
the field will call up a File Select dialog, whereas a HIT will open up the
field for editing.

Target
------
Select which job should receive the typed text. A DO on the field or its
label calls up a Job Select dialog, whereas a HIT will open up the field
for editing. Note that Job 0 (SuperBASIC on a Bog-Standard QDOS system, or
the Primary Interpreter under SMSQ/Minerva), normally the "Job With No Name"
is always referred to in this list as "Interpreter 0". Please make certain
that the job you select is capable of processing keyboard input or you
are in for a REALLY miserable time!

Be very careful about selecting jobs that have been "buttonised" by using
the QPAC2 Button_Sleep Thing. TypeInFile will just send a Wake event to the
button, which is a "Shell" job - all characters are then sent to the button
and (probably) ignored. I may fix this in future versions. It is not a
problem for PE programs, such as QD, which have a Sleep button.

Pause Every
-----------
Some programs cannot accept input at the kind of speed that TypeInFile is
capable of delivering. Most notable are terminal emulators (because they
are limited by the baud rate and remote echo), and some Pointer Environment
programs that allow the use of the mouse to navigate and perform actions
while typing. You can set TypeInFile so that it will automatically pause
every nth unit (either character or line). When this happens, TypeInFile
pops to the top of the screen and asks you what you want to do next:
Either type in the next n lines/chars, type in everything left in the
file, or just give up. You may not need to use this facility at all, if you
choose the correct value for Wait (see below). A value of 0 disables this
function.

Chars/Lines
-----------
These two items serve two purposes. Firstly they choose whether a pause
occurs on every n characters, or every n lines. Secondly, they choose
whether TypeInFile attempts to read and type its input file character by
character or line by line. The latter is considerably faster but may not be
popular with some slower programs. On a Super Gold Card, running SMSQ,
my experience is that the Job With No Name can always accept typing by Lines,
does not need to be paused, and will tolerate a zero Wait factor. The
MasterSpy can also cope with this. However, under JM QDOS on the same
hardware, I have to set a Wait Factor of 1 for the interpreter to accept
any characters at all.

Wait
----
Adjust this value so that the program you are sending characters to does not
lose any. I'm afraid that you may have to just "Suck it and see" here, it
really does depend upon the software. The value is used to enter a tight
timing loop that just wastes CPU time, so I'm afraid the value is also
processor dependent. The value here is applied for every character sent, so
if you have "Lines" selected, after the line is typed the program will pause
for the Wait Factor multiplied by the number of characters. It's always
worth setting this to zero to see what happens!

Scrap
-----
Select this option to type in the contents of the Scrap, instead of a file.
In this case, the Source field is replaced with the string <SCRAP>. This is
very useful for cutting and pasting text into a non-Scrap compliant editor
such as the MasterSpy.

Type In
-------
This will only be enabled if you have specified a valid filename and a
valid Job. DO it, or HIT it, and TypeInFile starts typing away. Note that
the target job will be picked to the top of the screen and sent a Wake event
just before any typing starts.

Stopping TypeInFile
-------------------
The big problem with programs like TypeInFile is that they can be REALLY
annoying if things get screwed up - sending keystrokes all over the place
(and you can just bet that they'll correspond to the exact shortcut key
sequence to select and delete that 800K document you've been working on
all day long!). The first step to avoid this kind of problem is not to
start switching jobs while TypeInFile is running - if you do this you will
definitely get keystrokes ending up in the wrong job, and you probably
won't be very happy about it! If all else fails, press and hold (together)
the [CTRL], [ALT], and [SHIFT] keys - and keep them down! Depending upon
whether you are in Character or Line typing mode, TypeInFile will halt
the next time it tries to type in some more text. You will then be given
the option to abort.

Editing Fields
--------------
Whilst editing a field, most of the standard QDOS editing keys work
as expected. But there are some additional keys which are worth knowing
about:-

[SHIFT]+[SPACE] (Normally the [INSERT] key on a PC keyboard) toggles between
insert and overwrite modes.

[CTRL]+[S] will insert the contents of the scrap at the current cursor
position. Be careful with this, the Scrap can hold a LOT of data!

[CTRL]+[SHIFT]+[S] puts the current contents of the edit buffer into the
Scrap, overwriting anything already there.

[CTRL]+[SHIFT]+[H] puts the current contents of the edit buffer into the
HotKey System II Stuffer Buffer.

[CTRL]+[SHIFT]+[F] calls up the Menu Extension's Character Select dialog,
allowing you to select any character to insert at the current cursor
position.

Command Line
------------
TypeInFile will accept a command line that must consist of the file name
followed by the name of the target job. Optional switches may be included
at any point in the command line:-

        /X      Assuming that both a source filename and a target job
                name have been supplied, this causes TypeInFile to
                immediately start processing and exit when the file
                has been typed.

        /B      Used in conjunction with /X, this switch causes the
                program to execute entirely in background mode. In this
                state, the program does not display a window, nor does it
                present any dialog boxes. Any confirmation requests are
                taken as YES, and the Pause facility is completely
                disabled.

        /W      Used in conjunction with /X, causes the program to pause
                on completion and display a dialog box confirming that
                the file has been typed in.

        /S      Type in the Scrap contents instead of a file.

        /L      Select type and pause by Lines.

        /C      Select type and pause by Chars.

        /0      Ignore any channels that have been passed (see note below).
                This facility is only useful in cases where the program has
                been launched by a shell that automatically sets up the three
                channels stdin, stdout and stderr.

        [P,W]   Specify the values for the pause multiple and the
                Wait Factor (The square brackets are manadatory).

Some jobs have spaces in their names. If you need to use spaces in the job
name enclose the name in either single or double quotes.

Examples:-

        EX 'TypeInFile_obj';'WIN1_Boot Interpreter 0 [0,0] /x /l'

        Type your boot file back into S*BASIC, at maximum speed!

        EX 'TypeInFile_obj';'Dummy Master_Spy [0,0] /s /x /l'

        Paste the Scrap straight into the Master Spy at maximum
        speed! Note the use of a dummy "Place Holder" for the
        source filename - this is ignored because the /s switch
        is specified, but there has to be something there for the
        command line to be correctly parsed.

        EX 'TypeInFile_obj';'WIN1_Boot "SBASIC Formatter" /x'

        Passing a Job Name with spaces in it.

You can also pass a channel to TypeInFile with the EX and QX commands,
this channel is taken as the source of the text to be Typed In. This
can be useful for, say, piping the output of a program into a text
editor.

Example:-

        EX 'DirList_obj';'/x /b' TO 'TypeInFile_obj Master_Spy [0,0] /x /b'

This pipes the output of my DirList utility into TypeInFile, which then
types the text into the (already running) Master Spy editor.

If three channels are passed, these are taken to be stdin, stdout and
stderr, and the program assumes that it has been launched from a UNIX-like
shell and should act as if it were a simple command-line utility. In
these circumstances, the /X and /B switches are automatically forced on.

Configuration
-------------
TypeInFile has three configuration items to set the default mode of
operation to what works best in your environment.

Pause every (L)ine or (C)haracter
---------------------------------
Choose L for pause by lines, C to pause by characters.

Pause every nth Line/Char
-------------------------
Specify the number of Lines or Characters at which a pause should occur.

Inter-Character Wait Factor
---------------------------
Set the Wait Factor to be applied on a per character basis.

Requirements
------------
TypeInFile needs the Menu Extension from Jochen Merz to be resident, as
well as Toolkit II. The program is compiled with QLiberator v3.33 (with
the 3.36mod run-times). The file TypeInFileRT_obj includes these runtimes
bound in.

Revision History
----------------
0.20    14/02/1998      First version
0.25    23/02/1998      Support for /B added.
                        Support for channel passing added.
0.30    01/03/1998      Copes with multiple channels passed
                        (i.e. stdin, stdout, and stderr)

License Terms
-------------

You are granted a license to use and distribute this software. The
terms of this license are stated below.

Provided that credit is given to the author, and that such credit is
included in any accompanying documentation, whether it be on written
or electronic media ...

1) This program may be freely distributed.

2) This program and its documentation may be incorporated as part of
another package, so long as it does not form the major or substantial
part of such package, and so long as, when taken in combination with
other programs supplied by the author under the same terms, the programs
together do not form the major or substantial part of that package.

3) The executable(s) may be modified, or patched, as necessary, to suit
different target environments. However, where such alterations are made,
and the executables are distributed, details of these changes must also
be included in electronic or written form.

No charge may be made for this program, other than reasonable costs of
electronic media and data transmission to facilitate its distribution.

The author gives no warranty as to the suitability of the program, or
the accuracy of the documentation. The programs are supplied 'as-is'.
It is the responsibility of the user to establish whether the program
is suitable and safe to use in his/her environment.

The author accepts no responsibility for any data that is lost or
corrupted as a result of using this program.

The author will make his best endeavours to fix any problems that are
reported to him, but does not accept an obligation to do so. The author
may be contacted via the E-Mail address quoted at the foot of this
document.

Adrian.D.Ives
ADIves@aol.com
01/03/1998
