Help file for !CDPlay
~~~~~~~~~~~~~~~~~~~~~

 Application  :CDPlay
     Purpose  :Filer Like CD Player
     Version  :1.00
      Author  :Leo White
        Date  :04-11-96

 Leo White, 1996


 The !CDPlay directory should contain the following files:
     -!Boot
     -!Help (This file)
     -!Run
     -!RunImage
     -!Sprites
     -!Sprites22
     -Choices (Will create default choices file if this isn't found)
     -Listing (Listing of CD's.  If not found, an empty one will be created)
     -Resources
        -CDFilter (Module to trap adjust clicks on CD Icon) 
        -Sprites (Play, rewind, pause buttons etc.)
        -Templates
        
--------------------------------------------------------------------

Introduction
~~~~~~~~~~~~

  !CDPlay is a utility for playing Audio CD's.  It was written by me
when I got a CD-ROM drive for my 4MB A5000, and discovered that the
supplied CD Player took up 160k of memory.  After looking round at
numerous other CD Players, and not finding any reasonable ones
that take up less than 96k I decided to write my own, and this is
the result.

  !CDPlay tries to present you with a 'Filer-Like' display when you
open the main windows.  i.e. It shows you the track number, name and
size in the same sort of format as the 'Full-Info' filer option 
displays them.

  It can support several CD ROM drives, enabling you to use
just the one program to control many drives.  And can store the
Titles and Track Names of CDs on disc, and recall them when you
next use that particular disc.

  !CDPlay also has functions for playing Random tracks, and allowing
the user to insert a program, specifing which tracks !CDPlay should play.

--------------------------------------------------------------------

Instructions
~~~~~~~~~~~~

  The Main Window
  ~~~~~~~~~~~~~~~
  
  As !CDPlay is designed to be loaded for playing Audio CD's, I 
decided to not clutter up the icon bar with an icon for my program.
Instead there are two ways of opening/closing the main window.
The first is to click adjust on the CD drive icon on the icon bar.
The second is to press CTRL-SHIFT-TAB, which will also open/close
the main window, but is not as reliable as some applications 
either don't pass on the keypress or use it for their own purposes.

  The top icon in the main window displays the Title of the CD,
this icon is writeable, and you can enter the title of the CD,
and it can be saved to disc so that it can be recalled by !CDPlay 
next time you use that CD.
The icon below it displays the name of the currently playing 
track.  Below these two icons are the CD Controls on the left, the
track number and playing time, and another set of control buttons.

  CD Controls
  ~~~~~~~~~~~
  
  When you first open the main window, these will be in the bottom left
corner.  They are, from left to right:-

	Pause    - Pauses/unpauses the CD
	Previous - Jumps to start of current track, or if already at the
		   start of the track, it jumps to the sart of the previous
		   track.  looping around from first track to last track
		   if necissary.
	Next	 - Moves to start of the next track.  Looping around from 
		   last track to first track if needed.
	Stop	 - Stops the CD
	Eject	 - Ejects the CD.  If the drive is already ejected, and
	 	   if the CD supports it, it will close the CD drawer.
	Play 	 - Starts to play the CD if it is stopped or paused.
	
  Track Info
  ~~~~~~~~~~
  
  This icon contains two pieces of information, these are:-
  
  	Track Number - The number of the currently selected track
  	Playing Time - This displays either the total time played from
  		       the start of the CD, OR the total time played
  		       from the start of the current track.  
  		       This can be toggled by clciking select on the icon.
  		       
  Control Buttons
  ~~~~~~~~~~~~~~~
  
  There are seven of these buttons.  When you first open the window,
they will be in the bottom right corner and perform the following 
actions:-

	I - This opens the Info window, displaying author's name,
	    version number etc.
	C - This opens the Choices window, where you can configure 
	    different parts of the program.
	S - Selecting this will cause the current CD information to 
	    be saved to disc, such as CD Title, track names etc.
	    This requires the use of a temporary file, and will
	    use the !Scrap directory if it is avaliable.
	R - Selects Random play mode.  When a track finishes playing, then
	    !CDPlay will choose another random track to play next.
	M - Selects Memory play mode.  This causes !CDPlay to play
	    only the tracks programmed into memory.
	P - This button opens the Program window, where you can select
	    what tracks are to be played
	Q - This button quits the program
	

The Choices Window
~~~~~~~~~~~~~~~~~~

  It is here that you can set up how !CDPlay acts.  In total there
are currently five options.

   Open Main Window On Startup - When selected, this causes !CDPlay to
   	automatically open the Main Window when the program is first
   	loaded.
   	
   Start Playing CD Automatically - When selected, this causes !CDPlay
        to attempt to play the CD in the current drive when it is first
        loaded, or when there is a disc/drive change.
        
   Show Track Length Played - When selected this causes !CDPlay to 
        display the total time played from the start of the current 
        track.  Otherwise it will show the total time played from the
        start of the CD.
        
   Stop CD On Drive Change - When selected, this causes !CDPlay to 
        stop the CD playing in the current drive before changing to
        the new drive number.
        
   Drive Number - Here you can select which drive numeber you wish
        !CDPlay to use.  The drive numbers range from 0 to 99, and can
        be changed by typing in the drive number, or by using the arrows
        to move the drive number up or down.
        
  Then there are three buttons you can click on:-
  
   Save   - Sets the choices and saves them to disc.
   
   Cancel - Unsets any changes made
   
   Set    - Sets the choices
   
The Program Window
~~~~~~~~~~~~~~~~~~

  Here you can select which tracks !CDPlay will play, and in 
what order.

  The icon shows you what the current status of the list is.
  
  After the icon, there are three buttons which can be used.
  
  Random     - Creates a random playlist containing all the tracks.
  
  Program    - Once selected, !CDPlay enters program mode.  When you
               click on a track number, instead of playing the track,
               !CDPlay adds it to the playlist.  Because of the way
               I am currently doing the list, you cannot add the same
               track twice.
            
  Clear List - This clears the memory list
  
The Track List
~~~~~~~~~~~~~~

  Underneath the control buttons, are a list of the tracks on the CD.
These are set up as follows :-

  Track Number - Starting from one, this is the tracks number.  Clicking
  		 this button will cause that track to be played (if it is 
  		 an audio track otherwise it will open the root directory
  		 of the CD), or if
  		 you are in program mode, for it to be added to the
  		 play list.
  		 
  Track Name   - This is a writeable icon, which contains the tracks name.
                 You can edit this yourself, and then can be saved to 
                 disc, so that !CDPlay can recall it next time you
                 use that CD.
                 
  Track Length - This icon contains the length of the track, in the format
  	         MM:SS - M = Minutes, S = Seconds.
  	         

The Listing File
~~~~~~~~~~~~~~~~

  The listing file is where !CDPlay stores all the CD Details that
it knows.  This list can be addex to be typing in the CD Details and
clicking he save button.  Or if you have another Listing file, then
it can be merged with the current file by dragging the new Listing
file onto the main window.  This will cause !CDPlay to nerge the 
two listings.  If the Listing files are large, then this could take
quite some time.
  !CDPlay can also read in Smart CD Version 2 listing files.  And will
merge it with its own in the same way as above.  But it can only add
the CD Details that contain the WhichDisc variable in the Smart CD 
listing file.

--------------------------------------------------------------------

Things To Do
~~~~~~~~~~~~

  -Make the scanning of the Listing file quicker.  Perhaps by building
   a look-up table of some description.
  -Make merging files quicker.
  -Change memory allocation routines.  malloc() seems to only be able
   to increase the wimpslot in 8k chunks.
  -Expand the memory play routines.  Allow saving of playlist etc.
  
--------------------------------------------------------------------

Program History
~~~~~~~~~~~~~~~

Version 0.01
~~~~~~~~~~~~

Created Template And Sprite files, And Copied Basic Code From 
My First Attempt At A CD Player

Version 0.02 Thu 12th September 1996
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Added Code To Make The Main Window Adjust Size And Create The Icons Needed
To Hold The Track Names Etc.

Version 0.03 Fri 13th September 1996
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Code Added To Detect Data CD's
If You Try And Play A Data Track, CDPlay Performs A Filer_OpenDir On
The Root Of The CD-ROM To Open The Filer Window
Link List Finished To Hold All The Track Informaton
Added Code To Generate The Playing Time Of The Track

Version 0.04 Tue 17th September 1996
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Added Memory Routines
Change Merge File Procedure So It Works With Native Files Properly

Version 0.05 Sun 22nd September 1996
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Tided Up The Code
Made Linked List Accessing More Memory Efficent And Faster

Version 0.06 Sat 5th October 1996
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Edited The Template Files To Make Them Conform To The RISC OS 3 Style
Guide To A Greater Degree

Version 0.07 Mon 7th October 1996
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Added Choices Window And Saving And Loading Of Choices File
Added Routines To Check If The Listing And Choices Files Exist

Version 0.08 Sat 12th October 1996
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Fixed Bug, If The CD Was Stopped By CDPlay, And Started By Another Method,
CDPlay Didn't Register The Fact That It Had Restarted
Added Routines To Set The 'Listing' File To Protected So That It Can't
Be Overwritten Or Deleted By Accident

Version 0.09 Sun 3rd November 1996
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Fixed Bug Which Stoppd !CDPlay Being Used On Multiple Drives
Added Code To Detect Return And Escape Keypresses In The Choices
Window, And Perform The Appropiate Action

Version 1.00 Mon 04th November 1996
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

First Release Version, Finally Decided The Program Was In A Fit
State To Be Released

Version 1.01 Mon 22nd November 1996
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Fixed Bug In Saving CD Listing Which Could Mess Up The Listing File

----------------------------------------------------------------

Disclaimer
~~~~~~~~~~

  This software is provided as is.  The author cannot take responsibility
for any loss of data or any other problems consequent upon the use of
this program.

Conditions of Use
~~~~~~~~~~~~~~~~~

  This software is freeware.  It may be freely distributed as long as no
money is exchanged, apart from cost of distribution i.e. cost of discs,
and that all the file are included except possibly the Choices and Listing
files.

----------------------------------------------------------------

Contacting The Author
~~~~~~~~~~~~~~~~~~~~~

  If you wish to contact me, e.g. to tell me about any bugs, 
improvements etc. Or if you just want to send me large amounts of
money :) (Well you never know), then you can use the following 
methods.

email : lptw1@ukc.ac.uk  (Should be valid for a few more years yet)

or send mail to

Leo White
208 New Road
West Parley
Ferndown
Dorset
BH22 8EN

Any mail arriving here will be sent on to me at Uni. So could take
quite some time to reach me.