<!-- Altered by Ian Macfarlane on 21-Nov-02 -->
     <html>
     <head>
     <title>
Solitaire for RiscOS versions 3.6, 3.7, 4+
     </title>
     </head>
     <body bgcolor="#fff0d8" text="#446600" link="#ff3333">
     <p><br><center><h3>Solitaire and Colotaire<br>
     <br></h3><h4>Version 7.18,  dated 21st November, 2002<br>
 by R.I.D.Macfarlane</h4><br></center>
<b>Contents:-</b>
     <ul>
     <li><a href="#intro">Introduction</a>
     <li><a href="#addhelp">Additional help</a>
     <li><a href="#int">International Languages</a>
     <li><a href="#cust">Customising the display</a>
     <li><a href="#env">Application Environment</a>
     <li><a href="#versions">Version History</a>
     <li><a href="#copyright">Software ownership and terms of use</a>
     <li><a href="#contact">Contact</a>
     </ul>
     <a name="intro"><b>Introduction</b></a><br>
This application demonstrates how a traditional board game
can be transferred into the RiscOS multitasking WIMP
system.  The author has used the application as a vehicle
to explore this system and unique routines for sprite, menu
and incarnation handling are included together with a drag
mechanism featuring pointer/sprite exchange.
     <p>
A control window allows the various options to be easily
setup and a second passive window can display a quarter
scale snapshot of the window containing the game. The
sprites, backdrop, control window sprites and template can
all be altered to customise the display. Optionally a random
function will produce a different veneer at each startup.
     <p>
The program will multi-task with itself or others.  Each
incarnation is given a different ball colour. There are
various help files, which are selected from the control
window and are available in either HTML or text form.
     <p>
     <a name="addhelp"><b>Additional help</b></a><br>
The following help files deal with specific areas, where help may be needed<br>               
     <ul>
     <li><a href="HelpPlay"><b>Game Play</b></a> gives instructions for
playing and application messages
     <li>The <b>HelpText</b> file provides messages for ACORN's Interactive Help application
as well as error messages for use by the program only.
     <li><a href="Soli_Help"><b>Solitaire Rules</b></a> and <a
href="Colo_Help"><b>Colotaire Rules</b></a> provide a summary of the rules
of the games and how to play them.
     </ul>
     <p>
     <a name="int"><b>International Languages</b></a><br>
All text including menu items may be displayed in any
foreign language that is supported by the system's
international module. All text files are to be found in
folders named as the country whose language they are written
in.  Any text files that are missing from a folder will be
loaded in from the default (English) folder.
     <p>
If you wish to create another folder, use the same name for
the directory as given by the *Country command.  The text
files are in free format, except 'HelpText'.  This file
comprises strings of text that are separated by the code
&#38;0d, Return and incrementing line numbers.  The program
finds the right string by counting down the number of
'Return' codes and checking against the embedded line
numbers, so that it is important that these are all
retained in the correct positions.
     <p>
The two characters '|M' can be used to start newlines
within a string of text for display by the Interactive
Application.  However only the first part will be displayed
in the error message box.  Note that there are only four
lines of text which are displayed by the application.
     <p>
Use the !Edit application; at the start, choose the CR&#60;-&#62;LF
option in the edit submenu to make the job easier, but
remember to reset this option at the end of the edit,
before saving the file.
     <p>
     <a name="cust"><b>Customising the display</b></a><br>
The Veneers folder contains several directories, who names
are used to specify the veneer type. There is a system
variable which may be specified in the !Run file to point at
the required veneer to be used on startup. This variable may
take the value 'Random' in which case different veneers will
be used for each startup.
     <p>
Each veneer directory may comprise the following file names
and if any are missing then the default files will be used:-
     <ul>
     <li>Choices: a text file holding the veneer's parameters
     <li>Sprites: a sprite file holding ALL the alternative sprites
     <li>Background: a sprite file holding the tile_1 sprite and optionally others
     <li>Templates: a template file defining the control window
     <li>CtlSprites: a sprite file for alternative radio and option icons
     </ul>
There is a degree of flexibility with the size and shapes of
the sprites allowed.  The size of the sprite used for the
hole (numbered 7) determines the framework and size of the
working area.   
     <p>
If the alternative radio and option icons are to be found in
the Background file rather than in 'their own' CtlSprites
file, then the background sprite will be used for both the
play and control windows [eg. the Yellow veneer]
     <p>
Some icons are missing intentionally from being shown but
must be retained in the template in order to keep the icon
numbering correct [they are hiding from view and therefore
cannot be selected, eg the Crail and Yellow veneers].  In
this case the values supplied by the respective Choices file
will be used for the missing functions.
     <p>
     <a name="env"><b>Application Environment</b></a><br>
The application is RiscOS compatible.  If the monitor in use is monochrome,
it is suggested that a two colour mode is chosen for display, since it is
otherwise difficult to distinguish colours in the Colotaire game.  Special
sprites have been constructed for the 2 colour modes and will be loaded
automatically.
    <p><a name="LargeFormat"></a>
A Large Format veneers folder has been added for the benefit of those with
an Iyonix or the Viewfinder system extension.  This folder is automatically
selected when the number of screen pixels exceeds 1500 in the x direction.
This can also be effected with a RiscPC with 2Mb VRAM by selecting the
screen size 1600 x 600 in either 256 or 32k colours.
     <p>
The original program was designed to use the ColourTrans
module in order to plot scaled sprites and change the
pointer to a ball during a drag function.  This is no longer
supported by versions of the program greater than 7.00. 
However deep coloured sprites (16M and 32k colours) can be
used for the balls, etc and can be dragged around the screen
as expected. This does restrict the application to working
in a RiscOS system with a version number equal to or greater
than 3.60.  Use Solitaire <a href="#versions">version 5.13</a>
if this is a problem.
     <p>
The default sound voice 'StringLib-Hard' is used to indicate user errors. 
If absent, the current bell voice will be used.
     <p>
The modules, 'HOLED' and 'BELL', written by Gordon J. Key,
from the excellent golf program 'HoledOut' [ Published by
the 4th Dimension ] have been added to the application's
directory to provide interesting sound effects.  These are
supplied with the permission of the owner of the copyright,
to whom the author expresses his thanks. These have been
converted to 26 / 32 bit neutral for use with Risc OS
version 5.
     <p>
The application attempts to make the sound facilities
multi-user friendly, by removing channel assignments and
voices at the end of use.  The sound menu selection will
also attempt to reload any voices and reselect any channels
that may have become deselected by other applications.
     <p>
     <a name="versions"><b>Version History</b></a>
     <table align=left cellspacing=2 cellpadding=2 width=100%>
     <tr><td>1.00</td><td>12-Jul-1990</td></tr>
     <tr><td>2.00</td><td>21-Oct-1990</td><td>Second passive, quarterscale window</td></tr>
     <tr><td>3.00</td><td>27-Dec-1990</td><td>Sound functions added</td></tr>
     <tr><td>4.00</td><td>07-Jan-1991</td><td>Standard routines to library</td></tr>
     <tr><td>5.00</td><td>07-Apr-1991</td><td>International text release</td></tr>
     <tr><td>5.12</td><td>20-Apr-1995</td><td>Country error [RiscOS 3+] fixed<br>Error reporting for RiscOS 3.5+</td></tr>
     <tr><td>5.13</td><td>18-Dec-2000</td><td>Several errors corrected<br>!Sprites22 file added</td></tr>
     <tr><td colspan=3><strong>For systems with RiscOS version 3.60 and above:-</strong></td></tr>
     <tr><td>7.16</td><td>15-Jan-2001</td><td>Control dialogue window replaces menu<br>Customising veneers added</td></tr>
     <tr><td>7.18</td><td>21-Nov-2002</td><td>RISC OS 5 compatibility</td></tr>
     </table>
     <p>
     <a name="copyright"><b>Software ownership and terms of use</b></a><br>
The author, R.I.D.Macfarlane, retains copyright, whilst the
material is in the Public Domain.  This means that you can
copy the application and its files, but no part of it can be
copied for commercial purposes or charged for or included on
a disk for which a charge is being made.  The application
must not be changed, with the exception of the !Boot and
!Run files and additions to the Veneer and Text folders.
     <p>
This readme file must always accompany the application. The
application must not be uploaded to a bulletin board. These
copying rights may be withdrawn if they are found to be
being misused.
     <p>
     <a name="contact"><b>Contact</b></a><br>
You can e-mail myself, Ian Macfarlane at:-<br>
<blockquote>ian@maceng.karoo.co.uk</blockquote>
The web-site is at:-
<blockquote><a href="http://www.maceng.karoo.net/BG/solitaire.html">http://www.maceng.karoo.net/BG/solitaire.html</a></blockquote>
or more briefly:-
<blockquote><a href="http://Solitaire.riscos.org.uk">http://Solitaire.riscos.org.uk</a></blockquote>
     </body>
     </html>
