____________________________________________________________________________

                                  M a k r o
                                      
                            Automatic text entry

                          by David Thomas,  1993-9
                         version 1.57 (02 Jul 1999)
____________________________________________________________________________


 Introduction ______________________________________________________________

Makro is a utility which allows you to define simple string sequences and
then play them back, as if you had typed them in at the keyboard.  This is
most helpful in cases where a series of repetetive actions need to be carried
out.

Makro allows you to maintain many different sets of macros and it allows you
to specify *Commands, so you can use it for, say, an e-mail address book
_and_ an application launcher.

Version 1.50 is a complete overhaul of the way Makro works - it now installs
on the iconbar, has real window gadgets and you can now have named macros. 
For each macro, there is now name and string fields which are edited via
a dialogue box.  This makes it much easier to tell what each macro does. 
Many thanks to Bob Harding and others for suggesting these changes.


 Usage _____________________________________________________________________

When loaded for the first time Makro will install its icon on the icon bar. 
Clicking SELECT on this icon will open Makros main window which, at this
point, will in the bottom-left hand corner of the screen.

The main window consists of a display and pop-up menu selector, left and
right bumper icons and twenty horizontal slabs.  Each of these slabs can be
programmed to contain a macro and each windows worth of slabs can be saved -
known as a macro set.

The display icon shows the name of the current macro set, at the moment it
will be Empty.  Clicking on the pop-up menu selector next to the  display
will open up a menu listing of the different macro sets you can load (Makro
is supplied with several).  Clicking on the left and right bumper icons will
take you through the macro sets available.

To define a macro, click MENU over any of the slabs.  A menu will appear with
Edit macro, Save set and Clear set entries on it - Edit macro is the
one were interested in - move the pointer right to open the Edit macro
dialogue box.  The dialogue box consists of two writable fields and two
action buttons.  They are:

     Name writable
       Enter in here the name of the macro,

     String writable
       Enter in here what you want inserted when the slab is clicked on,

     Store button
       Will enter your macro into the slab you clicked over,

     Cancel button
       Cancel will shut the window without making any changes, or
       alternatively when clicked with ADJUST will restore the original
       text.

When youve entered what you want into the writable fields, click on the
Store button (or press Enter) and your macro will be stored in the slab you
clicked over.  When you now click with SELECT on the slab, the string
associated with it will be inserted into whatever document or application
currently has input focus (signified by a cream-coloured surround.)  Also,
clicking with ADJUST will enter the macro name, rather than the string.

Some strings, which contain special characters, may not be inserted in
exactly the same way you wrote them, see the String Format section below to
find out how to avoid this.

*Commands can be defined simply by entering the command you require in the
String writable, with a preceeding *.  If you need to use a string which
starts with *, then enter <42> instead (which will insert an *.)


You can also press Ctrl when the pointer is over one of the slabs to insert
the associated string.  This is useful for menus and dialogue boxes which
would otherwise be closed.  However this facility can get pretty annoying
when you forget you have the pointer over the Makro window.  So, there is an
option icon in the top right-hand side of the window which toggles this
facility on or off.  The state of this option is saved in the choices.


The Save set dialogue box allows you to save your currently defined macros
to a named set, which will from then on be available from the Load menu. 
This dialogue box is also used to delete macro sets - load the unwanted set
into Makro and then save it with nothing in save boxs Name field - the set
will be deleted.


The Clear set entry simply does that - wipes all the macros and renames the
current set Empty.


The Sort set entry sorts the macros alphabetically by name.


There are also an entry available from the icon bar menu:
  
   Save will store to disc the current macro set and position of window. 
    These options are automatically restored each time Makro is run.


 String Format _____________________________________________________________

All strings are passed through the RISC OS string translator (OS_GSTrans)
prior to being inserted.  This enables you to easily insert control
characters and system variables.  So things like <Sys$Time>|M will be
expanded into the form 19:51:42 and then a newline.

However, to facilitate this certain characters must be reserved, or take on
special actions.  Basically this means that strings enclosed in angle
brackets are turned into system variables (or characters) and characters
prefixed by | are turned into control characters.

To insert the actual characters (< and |) you must either enter their ASCII
codes in angle brackets or prefix them with the control character |.  For
example:

                           Insert  String needed
                           ------  -------------
                              |          ||
                              <          |<

Control characters you may find useful are:

                           String  Action
                           ------  ------
                             |M    Return
                             |C    Copy in most editors
                             |X    Delete/Cut in most editors
                             |V    Move in most editors

You can also enter ASCII codes directly by enclosing the code in angle
brackets.  Base 10 is assumed, but other bases can be used by prefixing the
number with the base number and then an underscore.  For example, <33>
generates ! and <16_7E> generates ~.


 Notes _____________________________________________________________________

  The maximum string size is 255 characters, the maximum name size is 20
   characters.  The maximum number of characters which can be generated
   from a macro is 511 characters.

  Dropping a text file on one of the slabs will load in the first string
   or the first 255 characters of the file, into the slab.

  Any enhancements you want me to make then do contact me, rather than just
   sitting there muttering to yourself. ;-)


 Example Files _____________________________________________________________

A number of example files are provided to demonstrate Makro.  Load the
examples by selecting the appropriate entry from the Load menu.  They are:


  HTML  HTML Document Markup ___________________________________________

    This uses the standard RISC OS keyboard shortcuts to surround the
    currently selected text with HTML tags.

    It is slightly tricky to get these to work as HTML tags are surrounded
    by angle brackets ( < and > ) which means they will be interpreted by
    Makro as system variables.  The solution is to prefix the first angle
    bracket with a | (Ctrl) character.

    For example:

      Name: Bold
    String: |<B>|V|Z|</B>

      Name: Italic
    String: |<I>|V|Z|</I>


  E-mail  Address Book _________________________________________________

    This demonstrates how Makro can be used as an address book.

      Name: David Thomas
    String: dpt@tristone.co.uk

      Name: Justin Fletcher
    String: Gerph@innocent.com

      Name: Clares Sales Dept.
    String: sales@clares.demon.co.uk
  
    I am not affiliated with Clares in any way, btw!


  Reports  Report Creation Assistant ___________________________________

    Johnny is an excellent worker
             is a good worker
             is an average worker
             is a poor worker
             is a strange child... ;-)
             etc.


  Buttonbar  Application-Independent Buttonbar _________________________

      Name: Copy
    String: |C

      Name: Cut
    String: |X


  Launcher  Application/File Launcher __________________________________

      Name: Start Paint
    String: *WimpTask Filer_Run Resources:$.Apps.!Paint

      Name: Start Configure
    String: *WimpTask Filer_Run ADFS::4.$.!Boot

    etc.


 Macro Set Files _________________________________________________________

The macro set files are stored within the Makro application directory
(although their location can be moved by altering Makros !Run file.)  They
are contained in a directory called Sets.  The set files are plain text
with every two lines containing the Name and String for each macro.


 Versions __________________________________________________________________

1.57 (02 Jul 1999)
 - Added Sort set (Richard Torrens.)
 - Changed the icon.
 - Slight revisions to the templates and the example set files.

1.56 (01 Jun 1998)
 - Damn! Accidentally had a LEFT$() wrapped around the macro load.
   Meaning that macros would get truncated.  Introduced last version.
 - Reformatted this help file.
 - This versions section now in reverse chronological order.

1.55 (24 May 1998)
 - Macro names can now be up to 31 characters in length.
 - Where a macro file ends early, all subsequent buttons are cleared.
 - Adjusted validation strings slightly for ptr_write offsets.

1.54 (23 May 1998)
 - Increased number of macro buttons to 32 in response to request from
   Richard Whincup.  WimpSlot up 4K.
 - Gerphs e-mail address changed to innocent.com.

1.53 (31 Mar 1998)
 - Updated examples with my new e-mail address.
     (02 Dec 1998)
 - Changes to the bumper icon actions, to avoid GBPB errors.
     (21 Dec 1998)
 - Got mail from Michael Martin pointing out just how awful the Ctrl-insert
   function can be, so its now toggleable via an option icon. (Its saved in
   the choices too).
 - Main window is slightly wider now.

1.52 (25 Nov 1996)
 - Fixed sets menu builder to only display up to 20 sets, as opposed to
   crashing.  It also now properly sets the menu width.
 - Bob Harding suggested having a pop-up set selector and display for the
   name of the current set, and bumper back/forward icons.  Also changed the
   main window style to have a gap around the edges.  The bumper icons are a
   bit nasty (internally), but hey ho. ;-)

1.51 (05 Sep 1996)
 - Justin Fletcher pointed out how to get top-bit-set chars working.  Cheers
   mate. :-)  Slow mode removed.
 - I was doing the 1.05 bug *again* as the buffer-full check didnt actually
   work. :-(
 - Clicking SELECT on the Edit entry was opening the box without the text
   being updated.  Ditto for the Save entry.

1.50 (18 Aug 1996)
 - Just about everything changed.
 - Iconbar icon, proper window.
 - Different macro system - with a name and associated string.
 - OS_Byte call now checks for buffer full, and polls if so.
 - Uses Wimp_ProcessKey depending on new Slow menu entry; enables top-bit
   chars to get through. :-)

1.10
 - Intermediate 1.50 version.

1.06 (20 Apr 1994)
 - Increased macros to 24.
 - Fixed messed up insert routine (control chars werent being inserted)
 - Doesnt slab down on an empty slab anymore
 - Empty slabs dont cause insert anymore

1.05
 - Very odd bug, every 20th char was being missed out...

1.04
 - Added save function, as recommended by Arc World, it saves the window
   position too.

1.03
 - Added *Command interface.

1.02
 - Increased amount of macros from 4 to 16.
 - Added bit which loads first string from a text file if is it dropped on an
   icon.
 - Adjust-drag-on-slab-shadow works properly now.

1.01
 - Improved the input routine due to discovery of OS_Byte 153! Text appears
   instantly now!

1.00
 - First version



 Copyright & Contact Addresses _____________________________________________

This software is copyrighted work of David Thomas, it is supplied as is;
using it is entirely at your own risk.  I make no warranty as to the fitness
of this software for any purpose.  You are free to distribute this program
toanyone you please, as long as you are not supplying it for personal or
commercial gain and it is delivered with all of the supplied files unaltered.

If you have any comments, bug reports, suggestions for future versions or
anything else dont hesitate to contact me at -

  Mail:  Mr D.P. Thomas
         20 Rosebery Avenue
         Waterloo
         Liverpool
         L22 2BH

  Email: dpt@tristone.co.uk

  WWW:   http://www.tristone.co.uk/davespace/
_____________________________________________________________________________

