!KeysLib - Keystroke Library

This small application contains simple specially written BASIC programs for
use with Keystroke or Executor.

These programs allow many different operations to take place. For example: 
To take text from writable icons and perform an operation on the text then
replace that text with the altered version.

Or they read various settings of your computer.

HOW TO USE: 
***********

For example: The following two Keystroke commands converts the text at the
caret of a writable icon to UPPER case.

1) *COMMAND
Run <Keystroke$Lib>.Upper <Caret$text>
When this is performed, Caret$text will contain the contents of the writable icon containing the caret. This information is passed to the BASIC program and
it sets a system variable called KS$Line to the new text now converted to
uppercase.

2) INSERT TEXT
|U<KS$Line> This command deletes the text in the writable
icon and then places the contents of system variable 'KS$Line' in the
writable icon!

Variable 'Keystroke$Lib' contains the current pathname of Keystroke or
Executor's library directory. You do not have to manually type this name in as
Keystroke will automatically do this for you. Simply 'drag' the BASIC file
to the 'Run' icon in the *Command window.


Many of these functions can be supplied with parameters.
If the parameter is enclosed in '[]'s then that parameter is optional.

We have supplied several types of text changing programs:


ABC-Abc1 
-------- 
Converts 'example text' to 'Example Text' Use as shown
above.


Lower
----- 
Converts 'EXAMPLE TEXT' to 'example text' Use as shown above.


Upper
----- 
Converts 'example text' to 'EXAMPLE TEXT' Use as shown above.


Stripalpha
---------- 
Converts 'example1234' to '1234' or 'example123.45' to
'123.45' Use as shown above.


Stripnum 
-------- 
Converts 'example1234' to 'example' or 'example123.45' to
'example' Use as shown above.


Delay
----- 
This program takes a decimal value from the BASIC parameter and
delays for that number of seconds. 

E.g. Run <Keystroke$Lib>.delay 10.5 

A delay of 10.5 seconds will happen.


ForceAback
---------
This function when ran will force all the windows on screen to behind
the Pinboard! This is useful if you want quick access to the Pinboard.
See 'forcefront' below.

Use in a *command:
Run <Keystroke$Lib>.forceAback
No parameters needed


ForceAfrnt
---------- 
This function when ran will force all the windows on screen to in front
of the Pinboard! This is the opposite of 'forceback'.

Use in a *command:
Run <Keystroke$Lib>.forceAfrnt
No parameters needed


ForceWfrnt
----------
This function will force the window at the pointer to the front.
Use in a *command:
Run <Keystroke$Lib>.forceWfrnt
No parameters needed


ForceWback
----------
This function will force a window at the pointer to the back.
Use in a *command:
Run <Keystroke$Lib>.forceWback
No parameters needed


Wfront
------
This function will force the first window with the supplied name to the front.

Use in a *command
Run <Keystroke$Lib>.Wfront parameter1 [parameter2]

Parameter1 is the name of the window you want to force to the front.
ie
Run <Keystroke$Lib>.Wfront Text listing

This would cause a window with a title of "Text listing" to pop to the 
front. (Letter case is important).

Parameter2 (optional)
By including the parameter ' -F' at the end of the line the caret will
also be forced to that window.
ie
Run <Keystroke$Lib>.Wfront Text listing -F
(the space between 'listing' and '-F' is important!)

Note: this function starts from the back window to the front window, so if 
you had two windows on screen with one called 'Text listing number 1' and
another called 'Text listing number 2' then the one nearest the back will 
be brought to the front.


FullDate
--------
This function stores the current date in system variable KS$Line
as "22nd November '96" for example when run.

Use in a *command:
Run <Keystroke$Lib>.FullDate
No parameters needed

By Jim Wyllie.

Move2caret
---------- 
When this program is ran the pointer will move to the caret (if present). 
This is useful if you then wished to move or act upon the window with the 
current input focus.

Use in a *command:
Run <Keystroke$Lib>.Move2caret
No parameters needed

Caret
----- 
This program is designed to remember where the 'input focus'  or
caret is and then make it disappear when this program is run. When ran again
the input focus will reappear in the same window (if the window is still on
screen). This is useful if you are wishing to remove the caret from the
desktop, perform some operations on a window and then return the caret back
to it's original window!
This program must be used twice in a sequence.
Once to lose the caret and again to make it reappear.

Use in a *command:
Run <Keystroke$Lib>.Caret


Losecaret
---------
This program is designed to simply make the caret disappear from the Desktop.
This is useful if you want to lose the 'input focus' of an application.

Use in a *command:
Run <Keystroke$Lib>.Losecaret


Centrewin
--------- 
When ran, the program will automatically centre the window at the mouse pointer 
with respect to the Desktop. 
Example: 
Run <Keystroke$Lib>.centrewin [Parameter]

This program may have an extra parameter added to alter its effect.

[Parameter] is a number from 0 to 4

0. 
The window at the mouse pointer is centred. If this value is not present 
NO window is moved. 
Note: 
Run <Keystroke$Lib>.centrewin 
is the same as  
Run <Keystroke$Lib>.centrewin 0

1. 
The window at the mouse pointer is centred and forced to the top.

2. 
Only a window with the input focus will be centred. If it is not present
NO window is moved.

3. 
Only a window with the input focus will be centred and forced to the top.
If it is not present NO window is moved.

4. 
Only a window with the input focus will be centred and forced to the top.
If it is not present NO window is moved. Also the mouse pointer will move to
the window as well.


NOTE 
If the window does not have a title bar then it will NOT be moved but
the next window below it will be moved!


BrdCastURL
----------
When ran this function will inform a compatible Web browser like Fresco 
or Termite Internet that you wish to see this Web page.

Run <Keystroke$Lib>.BrdCastURL [Parameter]
where the parameter is a valid URL.
ie 
http://www.cybervillage.co.uk


Note:
Termite Internet V1.22 has a wee bug in that you must have at 
least one Web page up already for this to work. Oh hum...
V1.30 works OK though.

Iconiser
--------
***** This will only work on Risc OS 3 or later machines *****

When you run this program the window the pointer is over will be iconised
onto the Pinboard.

E.g.

Run <Keystroke$Lib>.Iconiser

The position of the top left of the window is where it will be placed
on the Pinboard.

Simple!


QuitTASK 
--------
This program will force any task (or program) of a given name to quit. 
Use in a *command:
Run <Keystroke$Lib>.QuitTASK parameter

Parameter is the task name. see text below.
E.g.
Run <Keystroke$Lib>.QuitTASK PAINT

Note:
It is important that you specify the task name as it appears in the task
display window and not the name displayed in the Filer window,  i.e. "Paint"
as opposed to "!Paint", or "Impression Style" as opposed to "!Style".

Note: 
The case of the word that you specify is also not important! 
E.g. "paint" is just as valid as "PaiNt"

 
SendText V2.00
--------------
This function is designed to be used with Impression Style,
Publisher (or Plus)
(!Edit, !StrongEd, Zap, etc. should use InsertText instead. See below).

It takes text from a parameter and sends it the working page if
there is a caret on it.

Note this will *not* insert text in a writable icon unless
that icon also allows text files dragged and dropped onto it.

Use in a *command:
Run <Keystroke$Lib>.SendText Parameter

Examples follow:
Run <Keystroke$Lib>.SendText Hello there
Impression/Edit will receive the text:
Hello there

or
Run <Keystroke$Lib>.SendText <KS$Line>
The contains of the variable 'KS$Line' will be placed.

or
Run <Keystroke$Lib>.SendText Hello {CR}there
Impression will receive the text:
Hello
there

(The curly brackets are standard DDF Impression text formating commands).
This would allow you to set up actions with the purpose of inserting
abbreviated words or sentences into Impression but you could also
insert for example a bold or italic word using these commands!
See your Impression manual for more on DDF commands.

For example:
Run <Keystroke$Lib>.SendText {bold on}Quantum{bold} Software
This places the word 'Quantum' in bold,but not 'Software'


Note:
We've noticed that Impression keeps the caret at the start of the
text inserted. So if you wish it automatically moved to the end of the
text then place a '>' character as your first letter.

For example:
Run <Keystroke$Lib>.SendText >{bold on}Quantum{bold} Software 

InsertText
----------
This is similar to SendText except that the DDF commands are not supported
and it will allow text to be inserted at the caret of any text editor.
 


SendWord
--------
This function is designed to be used with Computer Concepts WordWorks program.
It takes text from a parameter and tries to send it to WordWorks, if it
has a window open and the caret present.
Use in a *command:
Run <Keystroke$Lib>.SendWord Parameter

Parameter
The Parameter can be any characters or numbers, you may also use a
system variable. 

Example:
Run <Keystroke$Lib>.SendWord Hello
WordWords will receive the word 'Hello'


The following programs return values contained in system variables.
===================================================================

Date
---- 
Returns the current date in the form 'dd/mm/yy'
in the system variable KS$Line

Use in a *command:
Run <Keystroke$Lib>.Date

Date2
-----
Returns the current date in the form of that used by the system variable 
'Sys$DateFormat'in the system variable KS$Line

Use in a *command:
Run <Keystroke$Lib>.Date2

Typical output:
11:26:41 01-Nov-1996

See PRM 1-400 to see how to use this special variable.


Time
---- 
Returns the current time in the form Sun,06 Mar 1994.18:14:08
in the system variable KS$Line

Use in a *command:
Run <Keystroke$Lib>.Time

Countobj
--------
Counts the number of Filer objects contained in the
directory pointed by the BASIC parameter. 
The Keystroke system variable - KS$Line contains the number.

Use in a *command:
Run <Keystroke$Lib>.Countobj parameter

Parameter is a full filepath name.
ie 
RAM::RamDisc0.$
or
ADFS::HardDisc4.$.Images



Modenum
------- 
This returns in the system variable 'KS$Line' the current
screen mode number.

Use in a *command:
Run <Keystroke$Lib>.Modenum

Leaf
---- 
When supplied with a valid Filer path name, it strips off all
objects leaving just the leafname stored in KS$Line. 

Use in a *command:
Run <Keystroke$Lib>.Leaf parameter

Parameter is a full filepath name.
ie 
RAM::RamDisc0.$.fred
or
ADFS::HardDisc4.$.Images.01

E.g.
ADFS::DISC.$.qwerty.!ZXCVB Will leave '!ZXCVB' in KS$Line



Parent
------
When supplied with a valid Filer path name, it strips the leaf
object leaving just the parent name stored in KS$parent. 

Use in a *command:
Run <Keystroke$Lib>.Parent parameter

Parameter is a full filepath name.
ie 
RAM::RamDisc0.$.fred
or
ADFS::HardDisc4.$.Images.01


E.g.
'ADFS::DISC.$.qwerty.!ZXCVB' Will become 'ADFS::DISC.$.qwerty.'
Note the '.' at the end of the pathname.

If you use 'KS$parent2' then the '.' at the end will be stripped.
E.g.
'ADFS::DISC.$.qwerty.!ZXCVB' Will become 'ADFS::DISC.$.qwerty'

The leafname is also available, stored in KS$leaf
E.g.
'ADFS::DISC.$.qwerty.!ZXCVB' KS$leaf will store '!ZXCVB'


MouseSpeed
----------
When supplied with a parameter from 1 to 10 inclusive,
it sets the mouse speed of movement.
1 is a very slow mouse movement, 10 is very fast.

Example:
Run <Keystroke$Lib>.MouseSpeed parameter

Calling this function with a value of 1 is useful if you require
precise movement of the mouse pointer on the Desktop, perhaps when
drawing or painting.

If an incorrect number is entered, less than 1 or greater than 10,
then nothing will be changed. This is to stop the mouse becoming
impossible to control.


MouseRead 
--------- 
When this program is ran, the current X & Y position of
the mouse pointer is stored in two Keystroke variables - 
KS$LineX & KS$LineY

Use in a *command:
Run <Keystroke$Lib>.MouseRead

MouseWrite 
---------- 
When this program is ran, the mouse pointer is moved
to the X & Y position contained in KS$LineX & KS$LineY.

Use in a *command:
Run <Keystroke$Lib>.MouseWrite

Percent 
------- 
This program allows the user to take the numeric value of
text at a writable icon and alter it by a supplied percentage. 
This program requires two parameters to be supplied separated by a 
single space.

Example: Run <Keystroke$Lib>.percent parameter1 parameter2


Parameter1 
Ideally a number, but any letters (%,$,,mm,cm, etc.) will be
removed at the start.

Parameter2 
A number from -9999 to +9999. It may contain a '-' or '+' symbol
in front of it.

E.g.
 
1 
Run <Keystroke$Lib>.percent <Caret$text> +17.5 
If a number at a writable icon was 100 then KS$Line will contain 117.5

2 
Run <Keystroke$Lib>.percent <Caret$text> -17.5 
If a number at a writable icon was 100 then KS$Line will contain 82.5

The final calculated value is contained in KS$Line

Note: BASIC V has a limited ability to calculate to any high accuracy.


Wordsearch
----------- 
This program allows you to check for matching text
against another line of text. If the second parameter matches the first then
KS$Line is set to 1 otherwise it is set to 0.

Example: 
Run <Keystroke$Lib>.wordsearch parameter1 parameter2

Parameter1 
Ideally a number of words set by <Pointer$text>, etc.

Parameter2 
A single word or letter.

NOTE There must be a single space between parameter1 and parameter2. 
There must be a single space between '.wordsearch' and parameter1.

A working example: 

Run <Keystroke$Lib>.wordsearch <Caret$Text> test 

If the Caret$Text variable is set to 'This is a test function'. 
Then KS$Line would be set to 1 as 'test' is present.

Run <Keystroke$Lib>.wordsearch <Caret$Text> test 
If the Caret$Text variable is set to 'This is a TEST function'. 
Then KS$Line would be set to 0 as 'test' is NOT present. 

You can use also use any system variable as Parameter1.


CFSI-xy 
------- 
This program has been designed to be used with Acorn's
!ChangeFSI program to read the X & Y size of any image file loaded into
!ChangeFSI. 

Use in a *command:
Run <Keystroke$Lib>.CFSI-xy parameter


It can ONLY be used thus:
First there must have been a MANUAL Open dialogue command on !ChangeFSIs'
Source Info menu line from the main !ChangeFSI window so that the Source
Info window is open and the mouse pointer is within the window.

Then get Keystroke to perform a '*Command':

Run <Keystroke$Lib>.CFSI-xy <Pointer$Text>

The CFSI-xy program  will then read the text in the Source Info window
(because the pointer is there) and extract the X & Y size of the source
image file and store this information in KS$LineX and KS$LineY.


CFSIinfo
--------
This program is similar to CFSI-xy in that it returns the X & Y size
of the source image file and stores this information in KS$LineX and KS$LineY.
But it does *not* require !ChangeFSI to be loaded, just to been seen by the
Filer.
To use it via a *Command enter the following text.

Run <Keystroke$Lib>.CFSIinfo parameter1

Where parameter1 is the full pathname of the image you wish to read.

KS$LineX is the X or width of the image.
KS$LineY is the Y or height of the image.

Please note a temporary scrap image will be created by ChangeFSI in your
!Scrap directory when you use this, but the CFSIinfo program will automatically
delete it afterwards.
 

Move2IcnBr
---------- 
When this program is ran the pointer will move to the icon (if present)
on the icon bar. 
You will have to supply the exact name of the icon on the icon bar.
!Helper will give you this name. 

Use in a *command:
Run <Keystroke$Lib>.Move2IcnBr parameter
 
This is a useful function as in some cases you may want to place the pointer 
on an icon on the icon bar if you wanted to drag an object to it.

E.g. 
Run <Keystroke$Lib>.move2IcnBr !edit

If !Edit is on the icon bar, then the pointer will be moved there.


TaskLoaded 
----------
This program will check to see if a task/program is loaded, and return "0" 
if the task is not loaded, and "1" if it is.  This will allow you to define
a keystroke that will load a task if  it is not already loaded.

Use in a *command:
Run <Keystroke$Lib>.TaskLoaded parameter

Parameter is the name of the task in question

E.g. 
Run <Keystroke$Lib>.TaskLoaded Paint

followed by another linked *command,

If "<KS$Line>" = "0" Then Filer_Run Resources:$.Apps.!Paint

The first command will set KS$Line to "0" if !Paint is not loaded  and "1"
if it is.  It is important that you specify the task name as it appears in
the  task display window and not the name displayed in the filer window, 
i.e. 
"Paint" as opposed to "!Paint", or "Impression Style" as opposed to
"!Style".

Note: The case of the word that you specify is also not important! 
E.g. "paint" is just as valid as "PaiNt"


FileList
--------
This function takes a pathname and sets a system variable to each file object
or application (not directories) found within the directory pointed to by
the pathname.

Use in a *command:
Run <Keystroke$Lib>.fileList parameter

Parameter is a full pathname

Example of use.

Run <Keystroke$Lib>.FileList <Pointer$Text>
or
Run <Keystroke$Lib>.FileList RAM::RamDisc0.$

Each file object's pathname will be set to a system variable
called 'KS$dirX'. Where 'X' is a number from 1 to whatever.

The total number of objects found is stored in the system variable
'KSno'.
So for example a directory with two files and a directory within it
would have 'KSno' set to 2, and two system variables of 'KS$dirX' set.

Each file object's filehname will be set to a system variable
called 'KS$leafX'. Where 'X' is a number from 1 to whatever.


This is a useful function if you wish to know and perhaps alter any files
within a specific directory!

NOTE: Please note that if the popular product 'ImageFS' is loaded it very
probably will cause graphic files to be shown to FileList2 as directories.


FileList2
---------
This is identical to 'FileList' ,see above, except ALL Filer objects are listed.

NOTE: Please note that if the popular product 'ImageFS' is loaded it very
probably will cause graphic files to be shown to FileList2 as directories.
 


FileList3
---------
This function takes a pathname and sets a system variable to each file object
found within the directory pointed to by the pathname as long as it is a
bitmapped graphic object.

Use in a *command:
Run <Keystroke$Lib>.fileList3 parameter

Parameter is a full pathname

Example of use.

Run <Keystroke$Lib>.FileList3 <Pointer$Text>
or
Run <Keystroke$Lib>.FileList3 RAM::RamDisc0.$

Each file object's pathname will be set to a system variable
called 'KS$dirX'. Where 'X' is a number from 1 to whatever.

Each file object's filename will be set to a system variable
called 'KS$leafX'. Where 'X' is a number from 1 to whatever.

The total number of graphic objects found is stored in the system
variable 'KSno'.

This is a useful function if you wish to know and perhaps alter only
bitmapped files within a specific directory!

(If you find that it is ignoring a particular filetype then you may
have to add that type to the end of the internal DATA section of
FileList3, but this is unlikely). 

NOTE: Please note that if the popular product 'ImageFS' is loaded it very
probably will cause graphic files to be shown to FileList3 as directories.


FileList4
---------
This function takes a pathname and a filetype and sets a system variable
to each file object found within the directory pointed to by the pathname
as long as it is a matching object.

Use in a *command:
Run <Keystroke$Lib>.fileList4 parameter1 parameter2

Parameter1 is a full pathname to a directory

Parameter2 is either:
              A valid filetype name such as 'drawfile' or 'sprite'
              (lettercase is not important).
              A hexidecimal number (it must start with a '&', for example
              '&FFB' (lettercase is not important) which is BASIC btw)
              Or a plain number which is assumed to be decimal, ie 4096

If you wish to know the filetype name or number you can get this from the
Filer Info option if you click over a file.

There *must* be a single space between the two parameters.

NOTE: Please note that if the popular product 'ImageFS' is loaded it very
probably will cause graphic files to be shown to FileList4 as directories.



Example of use.

Run <Keystroke$Lib>.FileList4 <Pointer$Text> Drawfile
or
Run <Keystroke$Lib>.FileList4 RAM::RamDisc0.$ &FFB

Each file object's full pathname will be set to a system variable
called 'KS$dirX'. Where 'X' is a number from 1 to whatever.

Each file object's filename will be set to a system variable
called 'KS$leafX'. Where 'X' is a number from 1 to whatever.

The total number of objects found is stored in the system
variable 'KSno'.

This is a useful function if you wish to know and perhaps alter only
a particular type of file in a mixed filetype directory!

Tip: Directories are filetyped &1000 and applications (!boot, etc)
     are &2000 


FileTYPE
--------
This function returns the filetype of a filer object whose path has been
given.

Run <Keystroke$Lib>.FileTYPE parameter

The 'parameter' is a full pathname.
The filetype is returned in the system variable 'KSfiletype'
and is a hexadecimal number from 000 to FFF.
Also returned is the actual filetype name,
this is given by the system variable 'KSfiletypename'
and is a single word of up to eight letters.
If the computer does not know its name then the word
returned will just contain the hexadecimal number '&XXX'. 

This function is useful if you want to know that the file you are about
to work on is of the correct type.

NOTE: Please note that if the popular product 'ImageFS' is loaded it very
probably will cause graphic files to be shown to FileType as directories.


Random
------
This function returns a random integer number between 1 and the 
parameter specified.

Use in a *command:
Run <Keystroke$Lib>.Random parameter



The random number is returned in the Keystroke system variable KS$Rand.

For example
Run <Keystroke$Lib>.Random 10
will return a random number between 1 and 10 stored in KS$Rand.


PhoneDay
----------
This function is designed to alter 0X phone numbers to 01X.

British Telcom has told us that ALL 3 or 4 digit prefix codes in Britain must
now be 4 or 5 digits with 01XXX or 01XX instead of 0XXX or 0XX.
'081-123-45678' will become '0181-123-45678' or
'0506-411162' will become '01506-411162'.
But 5 towns are getting completely new codes and a prefix.
Plus a lot of mobile (Vodaphone,CellNet,Orange,etc.), BT and Mercury number
are remaining the same.

This program allows these numbers to be changed with ease.

Run <Keystroke$Lib>.PhoneDay parameter1

parameter1
Simply the phone number you want to change or findout if it needs to be changed.

Ideally this parameter would be made via the Keystroke Caret$text variable
from reading a writable icon of a database of some sort.

End result.
The new phone number is contained within the system variable 'KSPhone'.
 

Example of use:
Imagine that the caret is visible within a writable icon of a
database record and this icon has a telephone number in it.

In this example the writable icon may read '0506 411162'.

If Keystroke is set to do a -
*command:
Run <Keystroke$Lib>.PhoneDay <Caret$text>

followed by another action -

Insert text:
|U<KSPhone>

When ran the '0506 411162' will be placed within the variable 'Caret$text'
and examined by the function 'PhoneDay'.
It will match up the first 4 digits of the phone number. 

The 'Insert text' command will delete the text within the database's telephone
field and be replaced by the contents of 'KSPhone' which is now '01506 411162'.


Other examples:

Writable icon is 'Tel: 031-555-5704'
Run <Keystroke$Lib>.PhoneDay <Caret$text>
Gives 'Tel: 0131-555-5704' in variable KSPhone.

Writable icon is 'Tel: 010 91 506 53416'
Run <Keystroke$Lib>.Phoneday <Caret$text>
Gives 'Tel: 00 91 506 534166' in variable KSPhone.

You can imagine setting Keystroke to place the caret within a database
telephone field and calling these two commands. Then advancing to the next
record and looping back to the start of the Keystroke sequence until all
of your database records are converted. This is a potential huge time saver
over someone else doing it and perhaps making human errors!

Lastly, we have provided an optional use variable called 'KSmatch'.
It is always set to a specific value if certain conditions are met.
KSmatch = 0 if no change to the phone number happened.
KSmatch = 1 if the phone number was changed.
KSmatch = 2 if no phone number was presented for checking! (a blank field?)
KSmatch = 3 if the phone number has already been changed  to 01XXX, etc. 

This variable is only of use if you are wanting to create long complex
Keystroke sequences.

TIMERwrite
----------
This function sends an internal timer clock (not the main clock!) to zero
and if the function TIMERread is used, then the elapsed time between
the two events can be measured.

Run <Keystroke$Lib>.TIMERwrite
No parameters required


TIMERread
---------
This function will read the time elapsed since the function TIMERwrite was
used or since the computer was last reset or switched on.
Several system variables will contain the time data.

Run <Keystroke$Lib>.TIMERread
No parameters required

KS$Line contains the number of hours, minutes, seconds and centi-seconds
that have elapsed. Displayed in the format 'HH:MM:SS:CS'
KStime contains the TOTAL amount of seconds that have elapsed.
KShours contains the number of hours that have elapsed.
This is the HH part of KS$Line.
KSmins contains the number of mins that have elapsed.
This is the MM part of KS$Line.
KSsecs contains the number of seconds that have elapsed.
This is the SS part of KS$Line.

NOTE: IF another BASIC program uses the TIME statement then the elapsed
time may no longer be valid. 


EVENTStart
----------
This function allows the recording of multiple timed events.
It records the HH:MM:SS of the internal clock when ran.
It then stores this value in a system variable 'KSeventstartX'.
Where is X is an 'event' number from 1 to 9999.

You must supply it with this number as a parameter.

E.g.
Run <Keystroke$Lib>.EVENTStart parameter

This function is used in cojunction with EVENTfin to stop and
read the elapsed event.

Note:
Rerunning EVENTStart with the same number will cause that event to be
restarted with the current time.

The system variable 'KSeventstartX' is available if you wish to know
the time the event started.


EVENTfin
--------
This function allows the stopping and reading of a timed event
which has been started by EVENTStart.
To stop and read the elapsed time you must supply EVENTfin a
number from 1 to 9999.

E.g.
Run <Keystroke$Lib>.EVENTfin parameter

where parameter is a number. ie 1 or 21

For example if you started an timed event with a pervious
'Run <Keystroke$Lib>.EVENTStart 1'

To stop and read the elapsed time you must supply EVENTfin
with the same number.
E.g.
Run <Keystroke$Lib>.EVENTfin 1'

This sets a system variable called 'KSeventfinX', where X is the
number you supply, to the current time. So you know the time the
event stopped at.

Also and most importantly, a variable called 'KStimetakenX', where
X is the number you supply, to the elapsed time taken!

This is supplied in the format 'HH:MM:SS:TT'

Therefore to re-cap. 

'KSeventstartX' you will find out the starting time.

'KSeventfinX' will give you the finishing time.

And 'KStimetakenX' gives you the exact time difference between the two!


You can of course feed 'KStimetakenX' into a database via the Insert text
command. To do this you need to first set a dummy variable (KSvar) to the
contents of the 'KStimetakenX' via a *command.

In this example I've used the ability of Keystroke to pop up an input box,
so the user enters the number of the event to read. Assuming that the
number has been previously set by EVENTStart.

*Command
Seteval KSvar KStimetaken<Keystroke$Input>

Insert Text command
<KSvar>

E.g.
00:01:22:30 will be entered into any program that has the caret in it.

Note:
EVENTfin is set up to ignore numbers supplied which have already had
'KSeventfinX' set. This is to stop you accidently using EVENTfin on a number
you've already done and therefore not giving you a false finishing time.

Remember that once you've run EVENTfin with a number, that elapsed time
is stored in the computers RAM and will not change until you use EVENTStart
again or you switch off or reset your computer!

EVENTStart & EVENTfin was prepared for schools wishing to use their computer
for school sports day!

NOTE: Any use of another program that alters the internal system clock
will cause these timing to be wrong. eg a BASIC program altering the TIME
variable. But this is not likely.



ReadCMOS
--------
This function reads the CMOS RAM and can give the user some useful
information on the configuration of the computer being used.
(A lot of the CMOS RAM individual bit settings are used)
 
Run <Keystroke$Lib>.ReadCMOS parameter

Where parameter is a number (or system variable) from 0 to 239.

NOTE: Some locations have different uses under Risc OS 3 or 3.5/3.6

How to use example:
Run <Keystroke$Lib>.ReadCMOS 144
loation 144 contains the default RAM disc size in pagesize units.

The result is returned as a decimal number in KSram
Also in binary in KSram0 (LSB) to KSram7 (MSB)

So a RAM disc of 96K would be 3 pages of RAM (in a 4MB non Risc PC).
Therefore KSram would return '3' with
KSram0 & KSram1 both set to 1
KSram2 toKSram7 would be set to 0




\xxxSTRIP
---------

This useful function takes a single parameter which is either a file name
or a filepath and returns a Keystroke system variable with the PC DOS
type tag removed.

Run <Keystroke$Lib>./xxxSTRIP parameter[a]


For example, supplying 'FILE/TXT' as the parameter will return
KS$Line containing 'FILE' and variable KS$filetype would contain 'FFF'
which is the RISC OS filetype number for a text file.
You could then act upon this returned information in some way.

For example:
Set KS$file PICTURE/JPG
or
Set KS$file ADFS::HardDisc4.$.PICTURE/JPG
RUN <Keystroke$Lib>./xxxSTRIP <KS$file>

Output is...
KS$Line = 'PICTURE'
KS$filetype = 'C85'
(This is the RISC OS filetype number of a JPEG file) 

But we also realise that you may want to change the DOS file into an Acorn filetype automatically. So if you add the letter 'a' to the end of the
parameter and you supply a full pathname (ie ADFS::...) then that file will
have its filetype automatically translated.

For example:
Set KS$file ADFS::HardDisc4.$.PICTURE/JPG
RUN <Keystroke$Lib>./xxxSTRIP <KS$file>a
 
The file 'PICTURE/JPG' will be renamed to 'PICTURE' and set to a RISCOS
filetype of JPEG (&C85) automatically.

(System Variable 'KS$Leaf' is also set to the leaf of this altered pathname).

This function also checks to see that if in the renaming process the new
name might match another already present in the same directory.
In these cases the new file gets an extra number added to the end.

/xxxSTRIP automatically looks at the 'DOSMAP' command for filetypes, etc.

2DOS
----
This function takes a single parameter which is a pathname and if the
pathname is a Acorn type file it then converts the filename to a
PC DOS type and re-filetypes it to DOS.

Run <Keystroke$Lib>.2DOS parameter

For example, supplying a standard text file called readme as the parameter
will turn the file name to readme/TXT and filetype it to DOS.

If the file name is greater than 8 letters then the first 7 are used and
the last one is added to make up 8.

For example : 'Readme1st' becomes 'Readme1t' 

Notes:

Problems can occur, for example an SPARK, TAR or ZIP Archived files all have
the filetype Archive (DDC) on an Acorn. But 2DOS by default converts all
DDC files to /ARC which is correct for SPARK, but TAR files should be /TAR
and ZIP files should be /ZIP otherwise the PC will not read them correctly.

Any unknown Acorn types will be renamed as above, but will have no
PC file extension added.

2DOS automatically looks at the 'DOSMAP' command for filetypes, etc.


CMYK>RGB
--------

This program, when given the 4 parameters of CMYK as percentages will output
the RGB values as percentages in System variables 'KSr','KSg' & 'KSb'.
Use in a *command:
Run <Keystroke$Lib>.CMYK>RGB parameter1 parameter2 parameter3 parameter4

parameter1 is C
parameter2 is M
parameter3 is Y
parameter4 is K

For example :

RUN <Keystroke$Lib>.CMYK>RGB 0 12 87 13

will result in

KSr = 1.7 
KSg = 74.99
KSb = 87
These values are the RGB percentages.


OSVer
-----
This program returns the current RISC OS version number in system variable
RiscOS$Version

For example:

RUN <Keystroke$Lib>.OSVer
in a A5000 machine 
will set system variable 'RiscOS$Version' to 311
but when run in a A7000+ machine will return 370

This is useful in case you need to run two seperate actions depending on
what RISC OS Keystroke or Executor is running on.


ClseCmdWin (CloseCommandWindow)
-------------------------------
This function forces the small white, nonmultitasking command window that
can popup when issuing verbose *commands to close.

For example if you were performing a lot of *commands via an Obey file and
wished to return to the desktop when finished.

RUN <Keystroke$Lib>.ClseCmdWin



 
 

The following BASIC programs quickly alter various memory parameters of the
computer.
===========================================================================

minRMA 
------ 
When this BASIC program is run the Module area is reduced to minimum. 
This is exactly the same as the user manually placing the pointer
over the red bar 'module area' inside the Task Window and and trying to
reducing its length. A lot of programs seem to use the RMA area but few
reduce the RMA area once finished with it. ARCFS comes to mind here! 
This little program helps! Perhaps make this program 'autoexec' every 
minute or so?


minHEAP 
-------   
When this BASIC program is run the System heap/stack area is reduced to 
minimum. This is exactly the same as the user manually placing
the pointer over the red bar 'System heap/stack area' inside the Task Window
and and trying to reducing its length.



Special Applications 
====================

!Wait
-----
This program is designed to wait in the background for a number of seconds
that you tell it and then sets off a 'Keystroke xyz' command
(where xyz is the name you specify) and then removes itself from the RAM.

Why do this?
There are times when you want to make Keystroke perform an action after
a predetermined time delay. For example you get Keystroke to start off a
image scan via a scanning program like ImageMaster and then after the scan,
say 45 seconds, get Keystroke to print it automatically!

How to use it.
Run <Keystroke$Lib>.!Wait parameter1 parameter2

Please note you must ONLY use 'Run' *NOT* 'Filer_Run'
and you MUST supply two parameters.

parameter1
-S<the number of seconds you want it to wait for>
There MUST be -S at the start.

Example:
Run <Keystroke$Lib>.!Wait -S12 -Nwaitover
This will make it wait 12 seconds and send an action of 'waitover'.
or
Run <Keystroke$Lib>.!Wait -S2.5 -Nwait for it
This will make it wait 2.5 seconds and send an action of 'wait for it'.
or
Run <Keystroke$Lib>.!Wait -S<tim> -Nwaiting
Where 'tim' is a system variable set to the number of seconds you want.


parameter2
-N<The name of the action you want Keystroke to start doing>
There MUST be -N at the start.

Run <Keystroke$Lib>.!Wait -S<tim> -Nwaiting
Remember after the example above a Keystroke command of 'waiting' is send
to Keystroke. So in order for you to act upon this you'll need to set up a
Keystroke action called 'waiting'.
Otherwise nothing will appear to happen!


!winwatch
---------
This program is designed to wait in the background for a particular named
window and icon to appear and then set off a 'Keystroke <name you've supplied>'
command and then it removes itself from the RAM.

Why do this?
Imagine you want to format a disc, you can easily get Keystroke to start
off the format action. But Keystroke does not know when the formatting is
completed.

But if !winwatch is ran and told to look for a window called
'Format(ADFS 1.6M)', which is the name of the formatting window, and then
told to look for an icon in that window called 'OK'. Then !winwatch will
issue the command line 'Keystroke <name>' and so if you had a
Keystroke action called '<name>' that action would be started
and perhaps it would notify the user that the formatting is finished!


How to use it.
Run <Keystroke$Lib>.!winwatch parameter1 [parameter2] parameter3

Please note you must ONLY use 'Run' *NOT* 'Filer_Run'

You *must* start the parameters with  '-W', '-I' or 'N', see below.

parameter1
-Wexact name of window, case not important

example:
-WFORMAT (ADFS 1.6M) or -Wqwerty


parameter2 (optional)
-Iexact name of icon, case not important or #icon number

example:
-IOK or -I#7

So for the above example disc formatting example...

*Command:
Run <Keystroke$Lib>.!winwatch -Wformat (adfs 1.6m) -Iok -Nfound it

This will wait until the formatting window has an icon called 'OK'
and issue a Keystroke command to start the Action called 'found it'.

Another example...

Run <Keystroke$Lib>.!winwatch -Wformat (adfs 1.6m) -Nfound

This will wait until the Format window appears!
and issue a Keystroke command to start the Action called 'found'.

Yet another example...
Run <Keystroke$Lib>.!winwatch -Wdata input -I#8 -Ndoit

This line will wait until a window called 'data input' appears
*and* an icon on that window with an internal number 8 also appears.
(!Helper will show you what the internal number of an icon is).
(icons with changing numbers within it are icons with changing names
so you have to use the icon's internal number rather than its name)
and issue a Keystroke command to start the Action called 'doit'.
 
Remember you must also have a Keystroke action called 'doit' in order
for this to work correctly!

Last note...
!winwatch is designed to self-terminate after a certain time as preset
in the !Run file of !winwatch. This is by default 240 seconds (4 minutes),
if this is too short for you (or too long) then alter the line
mentioned in the !Run file of !winwatch to suit your needs. 

!winwatch2
----------
This performs very similar to !winwatch but it sends the Keystroke message
once the window (and icon) have appeared and then disappeared!

Why do this?
There are times when you want to terminate something once a process has
finished. You can use this function to detect a window and icon and then
once the window has gone then you can perhaps alert the user that the
process is finished. 

Say for example that a disc formating process has finished.

!wincheck
----------
When supplied with a task name it will set system variables:
KSaltered to Y if the title bar of that task's window has a '*' in it or
'N' if it has not.
It will also set KSinputfocus to Y if that window has the inputfocus as well.

*Command:
Run <Keystroke$Lib>.!wincheck2 <taskname>

<taskname> is the name as it appears in the Task Manager window.
Lettercase in not important. 

So if you run this function every 10 minutes on say PhotoDesk or Impression
(or any application which uses the '*' in its title bar to indicate an unsaved
condition) then you can check this flag and run a save operation in it! 


!PopUp
------
When this program is ran. A simple window 'pops up' to give the user
a message. Then the message window automatically disappears after a short
predetermined time period.

The message and time period may be adjusted to suit the user of Keystroke.

How to use it. 
Set a KS$Line variable to the message you want to appear followed by a number 
for the time period in seconds the message will appear for.

E.g. SET KS$Line [parameter1] [parameter2]

Parameter1 
A number of characters including any system variable if you wish.

Parameter2 
A positive number greater than 0 (1, 2.5, 6, etc.)

NOTE 
There must be a single space between parameter1 and parameter2. There
must be a single space between KS$Line and parameter1. If there is no
parameter2 then the time delay is preset to 1.5 seconds.

Examples: 
SET KS$Line Hello there 5

or 
SET KS$Line Set up My programs, please wait! 20

or using any system variable as well! 
SET KS$Line Today's date is <Sys$Date> <Sys$Year> 3


Then finally perform a *command running the !Popup program! 
For example: 
Run <Keystroke$Lib>.!popup


Also, if an extra two parameters (starting with 'X' or 'Y') are added
to the end of the !popup run command then the position of the pop up 
window may be defined in OS co-ordinates.

But this is optional, if no numbers are added then the window
will be automatically centred.   
For example :  
Run <Keystroke$Lib>.!popup [Xparameter1] [Yparameter2]

Xparameter1 
A positive number greater than 0 (1, 60, etc.) will position it
in the X axis.

Yparameter2 
A positive number greater than 0 (1, 60, etc.) will position it
in the Y axis.

(Origin is the bottom left of the desktop)

Please note the window can not be placed outside the desktop area.

Last points. If the user clicks with the mouse pointer on the message
window, then it will instantly close! 
If you do use the X & Y positioning parameters, then you can not 
use 'Filer_Run' as the launching command, you MUST use 'Run'.


Backit
------
This program is designed to make copy of directories and their contents
to another place in order to prevent losing valuable data.

Use in a *command:
Run <Keystroke$Lib>.Backit parameter1 parameter2

parameter1 is the source directory pathname

parameter2 is the destination directory pathname


How to use it.
The program requires two parameters, the first one being the pathname of the
source directory you want to copy, the second parameter is the place where
you want to store this data, the destination directory.

Now when this program is run, it first finds out the current date, ie
'11/05/96' and uses this name with 'bk' added at the end as a directory
to place the source directory you want copied.

eg :
Run <Keystroke$Lib>.Backit ADFS::4.$.files ADFS::4.$.backup

Will place a copy of the directory 'files' and all its contents into a
directory called '11/05/96bk' within the directory 'backup'.

Note: This function automatically limits itself to only three backed up
directories in your named directory. But you can easily alter this in the
top section of the program if you want more or less.

You could use this program to automatically backup important files every day
by including this a line like the one above in your !Boot file.

ReadWin
-------
Reads the current size,position and caret if present of a window with
the input focus.
Use with 'RestoreWin'

Use in a *command:
Run <Keystroke$Lib>.ReadWin 


RestoreWin
----------
Sets the position,size and caret of a window to the values provided by
'ReadWin'.
Use in a *command:
Run <Keystroke$Lib>.RestoreWin 

These two functions allow a user to set the position of a window, use 
'ReadWin' to record its current size and position and then alter it knowing
that by running 'restoreWin' they can quickly return to its former state.

Designed for use with !PhotoDesk, to enable the user to quickly change from
a much magnified image to a full size one quickly.

You could use this with and long DTP or word processor program like Ovation
or Impressionto store the current position of where you are in a document
and then move to another part and then quickly return to the previously
stored position!

Note: when we tried this with Impression it needs an additional text action
to follow the RestoreWin command as Impression does not update its windows
contents correctly.
You simply need to make it do a \PAGE UP\\PAGE DOWN\ in a text command
to force it to update its document window.


MergeSprs
---------
This takes two sprites, merges them into one sprite file and then saves
this file containg both over the 1st sprite file.

Use  in a *command:
Run <Keystroke$Lib>.MergeSprs <parameter1> <parameter2>

Parameter1 and 2 are full pathnames to two sprite files.

If parameter1 or 2 are not sprites or if they point to the same sprite
then nothing is done.

Note: Due to the possiblity of you trying to load huge sprites.
You are advised to place a *command with the following text in it:
WIMPSLOT -NEXT XXXK
just before using 'MergeSprs' as this will reserve some memory for
'MergeSprs' and prevent out of memory errors.
(The memory is automatically freed when 'MergeSprs' is finished).

XXXK is the maximum likely size in kilobytes of both sprites
your program may encounter.
Generally WIMPSLOT -NEXT 2000K should be ok.


ANTonline
---------
For use with the ANT Inetsuite program.
This function checks to see if the ANTsuite is loaded and if so it
forces the Suite to go online.

Use in a *command:
Run <Keystroke$Lib>.1.ANTonline

No parameters.


ANToffline
----------
For use with the ANT Inetsuite program.
This function sends an 'go offline' command to the ANT suite.

Use in a *command:
Run <Keystroke$Lib>.1.ANToffline

No parameters.


Flipjpg
-------
Use in a *command:
<Keystroke$Lib>.1.Flipjpg ADFS::4.$.picture
where 'ADFS::4.$.picture' is te path to a jpeg file.
When ran this program flips the Jpeg in the horizontal direction without damaging the data within.
note: if the image pixel width is not a multiply of 8 pixels then you may get a slight righthand edge effect.)


JpgOpt
------
Use in a *command:
<Keystroke$Lib>.1.JpgOpt ADFS::4.$.picture
where 'ADFS::4.$.picture' is te path to a jpeg file.
When ran this program optimises the data by removing any extra wasted data place within, usually by PC or Mac programs.
You can make a few Kbytes file savings sometimes.
This program does not harm the picture data in a normal jpeg.


RotateJPG
---------
Use in a *command:
<Keystroke$Lib>.1.RotateJPG ADFS::4.$.picture
where 'ADFS::4.$.picture' is te path to a jpeg file.
When ran this program rotates the image in a jpeg file 90 degs clockwise.
Note: the original file is overwritten.


HGlass_Off
----------
Use in a *command:
<Keystroke$Lib>.1.HGlass_Off
Turns the Hourglass of the Mouse Pointer OFF.


HGlass_On
----------
Use in a *command:
<Keystroke$Lib>.1.HGlass_On
Turns the Hourglass of the Mouse Pointer On.


***********************************************************************
These BASIC functions are supplied as seen and we envisage users making 
their own up and placing them in the 'Library' directory inside !KeysLib.
Please send us your own programs, they may be of use to others!

We only ask that any system variable you use must start 'KS' and
the 'Keystroke$Lib' variable is used for consistancy.

Note: Once you have used one of these programs, you must make sure that the
Keystroke$Lib variable has been set. You do this by simply showing the
application !KeysLib to the Filer.
If you've got the Library application in the !Boot Resources directory then
you've no worrys here.

Note: If there is no RAM in the 'Next' slot as seen in the Task window,
then the message 'Not enough Application memory to start BASIC' may appear.
************************************************************************
