 _______________   ________________________
/____  _____   /__/    ___     ____/ ___  /  By Martin Bazley
   /  /  __/_____   /  ____/  _____  ___  \  Version 1.03
  /__/  /__________/__/   /______/__/   |__|

This text is best viewed at a wrapwidth of 77 columns.
For interactive contents, do a 'List of Found' search for '==='.

=== 1 == Introduction ==

=== 1.1 == Preamble ==

Typer was originally written as a quick program partly to solve a problem I
had at the time and partly as an excuse to learn AppBasic.

It languished in this state for some time after I had used it to solve my
original problem, until one day I had a completely different problem and I
suddenly realised it could be solved in exactly the same way.

Then, sometime around this point, I came up with another use for it, and I
realised it was a bit crap, so I rewrote large parts of it.

Then I realised that other people might want to make use of my solution,
possibly in ways as yet undreamed-of, so I thought I might as well make a
proper release out of it.

=== 1.2 == Purpose ==

Typer is, at its simplest, a program to take a text file as input and send it
to the keyboard buffer.  This produces exactly the same effect as if you had
typed every character manually at the keyboard yourself (although much
faster).

This has two main uses:

1: Implementing a 'global clipboard' of sorts for applications which
don't have one and/or don't support IcnClipBrd (e.g. Firefox).

2: Entering repetitive text into dialogue boxes, for which Typer has several
additional functions to make life easier.

_____________________________________________________________________________

=== 2 == Quick guide ==

Typer sits on the icon bar.  It has no windows, other than the program info.
Clicking the icon initially does nothing.  At this stage it will appear
rather useless, unless you decide to read the help file or enable interactive
help.

To load a text file, drag it to this icon.  There will be no visible change,
but the program will now be active.  Any file is suitable, as long as it
doesn't contain control characters, with the exception of the Return and Tab
commands.

After loading a text file, you can click Select on the icon bar icon at any
time to send its contents to the keyboard buffer.  This means that the entire
text file will suddenly type itself at wherever the caret happens to be at
the time.  (If no window has the input focus, there will be no effect.)

_____________________________________________________________________________

=== 3 == Features ==

=== 3.1 == Basic functionality ==

Any file, from any program, can be dropped onto the icon, although ones with
control characters other than Tab (9) and Return (10, 13, or both) may behave
strangely.

All files are backed up inside Typer's own Scrap directory, to avoid
conflicts if the file later changes or disappears (or is overwritten by a
later data transfer).

There is no limit on the file size, as the program is disc-based and does not
claim any memory.

After a file has been loaded, it can be sent to the text buffer simply by
clicking on the icon.  It will then be copied verbatim to the current
position of the caret, be that in a dialogue box, a document editor, or a
web browser.

Loading another file after the first one will replace it.

Typer remembers its files, so if you quit and restart the program, the text
file last dragged will still be there, unless something has wiped the Scrap
directory in the meantime (for example, if you're a dinosaur who keeps Scrap
in a RAM disc).

=== 3.2 == Buffering behaviour ==

A number of workarounds are necessary to overcome the conflicts between text
as typed at the keyboard, and text as saved to disc.

Newline characters will be converted to a single CR.  Multi-character
newlines (e.g. the CR+LF produced by Windows) are handled properly.  More
than one type of newline in the same file may be unpredictable.

Tab characters will be converted to character &8A, which gets reported to
applications as &18A via the Key Pressed Wimp_Poll event.  This corresponds
to a Tab keypress with no modifiers.  This method both inserts Tab characters
correctly (if entering into a text editor) and correctly reports and
processes the keypress (if entering into a dialogue box - see later).

Character 0 is ignored.  Other control characters will be treated literally,
so watch out.

Characters with the top bit set will automatically be preceded by a 0,
according to the OS_Byte API, to avoid confusion with function key presses.
It took a bit of effort, but now character &8A itself () is treated this way
too.

As the buffer size is limited, and the limit is (on my computer) 128 bytes,
any text file which exceeds this will automatically be split across multiple
Wimp_Polls to give the buffer a chance to empty.

=== 3.3 == Use in dialogue boxes ==

Apart from copying large quantities of text from one location to another, a
job for which there are better tools, Typer can also fill in dialogue boxes
for you based on the contents of a short text file.

In most applications, the Tab key can be used to move between writable fields
in a dialogue box without need to resort to the mouse.  For this reason, if
the caret was in a dialogue box when you clicked the icon, every time your
text file contains a Tab character the caret will jump to the next writable
icon.

Usually the order in which it jumps around the icons is fixed, covers all of
them, and can be determined by experiment.  After this, you can produce text
files which contain the text to be entered in each field, separated by one
Tab character to indicate a jump to the next field.

Another commonplace shortcut in dialogue boxes is the Return key to simulate
a click on the OK button, so if you don't want that to happen you'll have to
make sure your text file doesn't have a newline at the end.

Typer has another feature which can be used to make filling in dialogue boxes
more convenient.  If the box came with text already in the icons and you
don't want to have to delete it, you can click Adjust instead of Select on
the icon.  This causes the program to issue a Ctrl-U (blank writable field)
keypress at the start of the file, and after every Tab character, so the
caret starts off in a blank field and automatically blanks each one as it
moves to it.

=== 3.4 == Notes and caveats ==

Clicking Adjust on the icon will always start off the text insertion with a
Ctrl-U, irrespective of the position of the caret or whether the file
contains any Tab characters.  Therefore, use Select for non-dialogue box
purposes.

Although Firefox can enter text extremely slowly, it seems to exhaust the
keyboard buffer very quickly, so if you're copying a large amount of text
into one of its text fields, the computer and keyboard should still be usable
while the text is ponderously appearing.

Personally, I find editing text in an external editor and copying it into
Firefox's text area to be an extremely wise precaution.  It reduces the
damage from a crash, it's less aggravating (because you can type at your own
speed and it doesn't glitch) and you can go off and do something else after
having set Typer to send it to Firefox.  For the first reason, it is also an
extremely wise precaution with NetSurf, although Typer is not necessary there
as NetSurf supports the global clipboard.

Another browser-related use involved the transfer of links NetSurf can't
handle into Firefox.  Load Typer, drag the URL from NetSurf's address bar to
the icon (this saves it as a one-line text file), load Firefox, position
caret in Firefox's address bar, blank if necessary (NB: Firefox does not
support Ctrl-U) and click on Typer to load the offending URL.  (The only
alternative is copying by hand.)

In dialogue boxes, I have found applications in ID3TagEd and DigitalCD's
file properties window, in both cases allowing me to enter large amounts of
information with relative ease.

Once more for luck: Don't trust control characters other than Tab and
newlines.

If the program is quit in the middle of a buffer insertion, the typing will
not stop instantly, as there will still be characters left in the keyboard
buffer.

AppBasic is not territory-neutral, and in the course of internationalisation
I did some rather drastic things which have conspired to break the manager.
In other words, you can run it compressed, but not decompressed.  Bear that
in mind when decompressing for the purposes of modifying code - you'll have
to compress it again before it'll work.  Also, be very careful to deselect
the 'Auto' option button in the 'Modules' window, otherwise it'll look for
the 'res' file and fail to find it, and the result will be a useless blank
file.  Unfortunately, it seems to be necessary to enter every dependency
manually, since AppBasic isn't clever enough to read its own Modules file.

Finally, I'm not 100% confident of everything, especially what happens when
certain characters coincide with a full buffer, so use at your own risk,
yadda yadda.  If you can break it, please send me the text file in question,
otherwise it'll be extremely difficult for me to know what's going on.

_____________________________________________________________________________

=== 4 == Version history ==

=== Version 1.00 == 19th January 2011 ==

   Program "finished".

=== Version 1.01 == 20th January 2011 ==

   Ensure all necessary Toolbox modules are loaded correctly.

=== Version 1.02 == 21st January 2011 ==

   Fixed bug affecting loading files dragged from a directory display (as
    opposed to from an application).
   Now detects if a scrap file exists on startup, and if so, uses that by
    default.  This preserves data between quits/resets.
   Corrected erroneous note about quitting - turned out I had thought to fix
    it after all.

=== Version 1.03 == 23rd January 2011 ==

   Now inserts only CR, instead of LF+CR, at a newline.
   Fixed issues with multi-character newlines (e.g. Windows text files).

_____________________________________________________________________________

=== 5 == The boring bits ==

=== 5.1 == Thanks and credits ==

The part of the program which does stuff you downloaded it for was written by
Martin Bazley.

This program has been created with AppBasic, a freeware BASIC development
library to facilitate easy Toolbox programming, written by Joe Taylor.  See
http://www.jettons.co.uk/appbasic/ .

ResFind, the program used to locate local resources, was written by Olaf
Krumnow and Herbert zur Nedden of the German Archimedes Group (GAG).

=== 5.2 == Legal stuff ==

This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
details.

You should have received a copy of the GNU General Public License along with
this program.  If not, see <http://www.gnu.org/licenses/>.

The application name Typer has been officially registered with RISC OS Open
Ltd.

If you're going to review or mirror this program, I'd appreciate knowing
about it!  (Especially if you're going to give it a good review. :-) )

=== 5.3 == Contact ==

Put your mouth to the cup and shout one of them email thingies down them thar
intertubes:

 mailto:martin@bazleyfamily.co.uk

Or donate some cash to our newly privatised overlords if you're so inclined:

Martin Bazley
Flat 8
349 North End Road
Fulham
London
SW6 1NN
ENGLAND

=== 5.4 == And finally... ==

Not had enough of me yet?  Why not listen to my rantings on Twitter?
http://twitter.com/swirlythingy

Sometimes I point a camera at stuff and then I upload the results to the
Internet and call it art.  Guaranteed bed-free zone:
http://swirlythingy.deviantart.com/

For RISC OS software by me, my sister Harriet and brother Christopher, as
well as Doom levels by the former and latter and free music by the former,
and much more besides: http://kingfishercorner.eu

=== End