                       Documentation for EVALuator V1.00
                       ---------------------------------

********************** Incredibly boring Copyright Notice *********************
*                                                                             *
*       All program code is the exclusive copyright of Richard K. Lloyd.      *
*            The program source and documentation for EVALuator are           *
* freely distributable and should not be charged for under ANY circumstances. *
*                                                                             *
*******************************************************************************

Installing EVALuator (Requires RISC OS)
---------------------------------------

Simply start up the Desktop and double-click on the !EVALuator application
directory. This will install an icon on the RHS of the icon bar, ready for
running by clicking on this icon with the left or right button. The middle
button just brings up the usual Info and Quit options which need no further
explanation here.

So what does EVALuator do ?
---------------------------

People who spend all their time in the Desktop (I don't for programming, but
that's just me folks) often, OK sometimes, wonder why they need BASIC at all.
Well, other than the fact that its used as the main language for an *awful lot*
of PD (and commercial !) Desktop programs, it's a great 'quickie expression
evaluator'.

However, there is a drawback: to stop BASIC destroying all the currently active
Desktop programs, you must use the awkward 'New Task' option in the Task
Manager and up pops a miserly window and all your tasks suspend whilst you're
in BASIC...all this for a miserly PRINT PI^2.8 or some such calculation !
Hence, it's RKL to the rescue again with a Desktop application which calls
EVAL itself in a nice friendly multi-tasking window.

How To Run EVALuator
--------------------

When you click on the icon bar icon, up pops a small window with two main
areas: 'Expression' (click on the white area to display a caret) and 'Result'
(this cannot be edited - there's no point...or even a caret). Once clicked on,
the Expression area allows the usual mouse/key actions (click, delete, CTRL-U
etc.) and the evaluation (passed to EVAL) of the expression is displayed IN
REAL-TIME in the Result area (hence you don't have to press RETURN).

If the Expression is a null string, then "No expression" is displayed in the
Results area. If the Expression begins with a tilde (~), then the Result is
shown in hexadecimal and prefixed with an ampersand (&). The Expression area
allows up to 99 characters, although it is much narrower than that to reduce
the overall window size - the input area scrolls automatically if you type
an extremely long expression.

Technical Details of Evaluator
------------------------------

Well, there's no a lot to say here. I originally developed the program on
a Macintosh Plus as a DA (using Turbo Pascal and...groan...my OWN expression
evaluator closely modelled on BBC BASIC's) and then on a MicroVAX II using
VAX Pascal (and you could assign/read DCL variables !). The program's one hell
of a lot shorter with the use of the wondrous EVAL.

Some moans to Acorn about the WIMP and !FormEd:

1. !FormEd is a right pain to use when you want to adjust the size of an icon.
   You have to *change* the icon's attributes to Click/Drag, do the adjustment
   with the right button and then set it back again ! AAARRRGGGHHH !!
   Windows can't be resized unless you add a V Scroll (inc. Size Icon) - not
   even the right button works...

2. Can anyone please tell me how to stop Wimp_ForceRedraw from completely
   ignoring the video refresh and flickering nastily when it updates the
   area specified ? No, putting a WAIT (*FX 19) before it doesn't work.

3. Why isn't the line number reported by errors in BASIC programs once they've
   done a Wimp_Initialise ?

4. Why doesn't a keypress inside a writeable icon return anything back via
   Wimp_Poll (specifically Event 8) ?

Revision History of EVALuator
-----------------------------

Version 1.00
------------

* A very quickly cobbled together BASIC Desktop program that replaces the need
  to run BASIC just do a calculation using the PRINT statement.

Future Improvements to EVALuator V1.00
--------------------------------------

* I'd like an resizeable window that would automatically resize the Expression
  and Result areas too.

* Some sort of cut/paste facility (does the Archimedes have a Clipboard - I
  don't think so).

Where to find me to report bugs or improvements to the EVALuator
----------------------------------------------------------------

Snail Mail           JANET e-mail
----------           ------------
Richard K. Lloyd,    rkl@uk.ac.liv.cs.mva
1, Banks Road,
Lower Heswall,
Wirral,
Merseyside. 
