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

 Application  :CDPlay
     Purpose  :Filer Like CD Player
     Version  :1.10
      Author  :Leo White
        Date  :20-3-97

 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)
     -Volume (Stores the volume selected when CDPlay is quit)
     -Resources
        -CDFilter (Module to trap adjust clicks on CD Icon Phillip Camp) 
        -CDMerge (Used to merge new Listing Files with current one.)
        -Config (Contains the configuration code)
        -CSprites   (Sprites for configure application)
        -CSprites22 (Hi-res sprites for configure application)
        -Sprites (Play, rewind, pause buttons etc.)
        -Sprites22 (Hi-res sprites)
        -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, specifying which tracks CDPlay should play.

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

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

  The Main Window
  ~~~~~~~~~~~~~~~
  
  As CDPlay is designed to be loaded for playing Audio CD's, I 
decided not to 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 (configurable), 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 writable, 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 volume control on the right.

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

        R        - When depressed, puts CDPlay into Random Play Mode
        M        - When depressed, puts CDPlay into Memory Play Mode
	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 start of the previous
		   track.  Looping around from first track to last track
		   if necessary.
	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.
	 	   ADJUST clicking the icon will always attempt to
	 	   open 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, the total time played
  		       from the start of the current track, the
  		       time remaining till the end of the CD,
  		       and the ti,e remaining till the end of the
  		       Track.  This can be toggled by clicking select 
  		       on the icon.
  		       
  Volume Control
  ~~~~~~~~~~~~~~
  
When you first open the window, this is on the bottom right corner,
and clicking on the bar will adjust the volume (requires CDFS 2.22,
and a drive that supports software volume of course :) )
	

The Menu
~~~~~~~~

  The menu contains the following options :-
    
    Info    - Opens the usual info window.
    Program - Opens the program window, allowing you to build up
              a program to be played.
    Choices - Starts up the configuration program, allowing you to 
              configure CDPlays options.
    Save    - Saves the current CD Details to disc when selected.
    Quit    - Quits CDplay.
    
The Choices Program
~~~~~~~~~~~~~~~~~~~

The choices application is a separate program to CDPlay
to keep the memory usage of the main program at a minimum.,
and is run when the 'Choices..' menu option is selected.

The program consists of four windows.  The function of each
window is described below.

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

  In the top half of the window are three icons.  You
can select click these icons to open the three main 
configuration windows.

  In the lower half of the window are several icons.  These are :
  
  Save current    - If this icon is selected, then when you save
  window position   the new configuration.  It stores the current
  		    position of the main window, which will
  		    be used to position the window when you
  		    next load CDPlay.
  		    
  Save - Select click this icon to save the configuration 
         as the default choices.
         
  Cancel - Select this icon to abandon changes to the configuration.
  
  Set - Select this icon to set the configuration, but not save it.
  		

The 'Drive' Window
~~~~~~~~~~~~~~~~~~

  In this window, you can set options which effect the drive.
Such as auto playing CD's, drive Number etc.

  Disable CD Scanning - Select this option to stop CDPlay from scanning 
                        the Listing file to find a match for the current CD.
                        
  Warm if track listings - Select this option to get CDPlay to warn
  are not saved            you if the listing file isn't saved.
  
  Start playing CD - Select this option to CDPlay to automatically start 
  automatically      playing CDs.
  
  Auto repeat CD - Select this option to get CDPlay to automatically repeat 
	           the CD/program when it has finished.
	           
  Stop CD on     - Select this option to get CDPlay to stop the CD when
  drive change     you change the drive number.
  
  CD matching   - Enter the 'error' factor that CDPlay will use to 
  offset          identify CDs. Should only need to be changed if you
  	          have more than one drive, or use someone else's
  	          'Listing' file.
  	          
  CD drive number - Enter the drive number you wish to use here.
  		    Can be in the range of  0-99.
  		    
  Set - Select this icon to set the current configuration.
  
  Cancel - Select this icon to discard any changes made to the 
           configuration.
           

  The 'Display' Window
  ~~~~~~~~~~~~~~~~~~~~
  
  In this window, you can setup what the main window displays.


  Show track lengths - Select this option to display the track
                       lengths in the main window.
                      
  Open window on  - Select this option to get CDPlay to open
  startup.          its main window on startup.
 
  Time Formats :
 
  From start of CD - Shows time from start of CD
 
  From start of track - Shows time from start of the current track.
 
  Till end of CD - Shows the time until the end of the CD
 
  Till end of track - Shows the time until the end of the current Track.
 
  Set - Select this icon to set the current configuration.
  
  Cancel - Select this icon to discard any changes made to the 
           configuration.
 
 
  The 'Miscellaneous' window
  ~~~~~~~~~~~~~~~~~~~~~~~~~~
  
  In this window you can set the options which don't
fit into the other two windows.

  Save volume - Select this volume to save the current volume 
  on exit       when CDPlay is quit.  Otherwise the volume will 
                be restored to full.
                
  Auto save   - Select this option to get CDPlay to automatically 
  CD listing    save the CD listing when Return is pressed in
    	        the last track icon.
    	        
  Stop CD when - Select this option to get CDPlay to stop the
  quit  	 CD when it is quit. 
  
  Autodetect  - When selected, this causes CDplay to check if
  CD Change     the CD currently in the drive is different to 
                the one it expects.  If your mainwindow seems
                to be redrawing all the icons occasionally, then
                turn this option off.
                
  Check if    - When on, this causes CDPlay to check if a track
  track is      is audio before playing it.  If U cannot play
  Audio         tracks, and get errors such as 'Cannot read Audio
  	        discs" then turn this option off.     

  Hotkey code - When this icon has the caret, it will take any
                keypress and work out its keycode and display it
                in the icon.  This will be used for the hotkey to 
                open/close CDPlay's main window.   
  
  Set - Select this icon to set the current configuration.
  
  Cancel - Select this icon to discard any changes made to the 
           configuration.

 
   
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.
                           
  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 track's 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 writable 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 added 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 merge 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
~~~~~~~~~~~~

  -Expand the memory play routines.  Allow saving of playlist etc.
  -Adding interactive help to the choices program.
  -Rewriting the entire program as a module.  So it works
   when you are outside the desktop (i.e. Playing games)
  
--------------------------------------------------------------------

Known Bugs
~~~~~~~~~~
  -Erm I can't recall any at the mo :)

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

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 Information
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Tidied Up The Code
Made Linked List Accessing More Memory Efficient 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 Stopped CDPlay Being Used On Multiple Drives
Added Code To Detect Return And Escape Keypresses In The Choices
Window, And Perform The Appropriate 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

Version 1.02 12 December 1996
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Different CDFS drivers (e.g. ATAPI, PSLCD) return different CD ID
numbers.  Added hack to enable CDs entered into the listing under
one driver, to be used by the other driver.
Tidied up some of the code

Version 1.03 4 January 1997
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Rewrote CD Play routines, and window creation/handling routines,
edited the sprite files and template files, resulting in a 25% 
reduction in memory usage.  CDPlay now only requires 48k of 
memory to run in, instead of 64k.
Also changed the 'memory' mode.  Can now handle having the same
track more than once in the Program.  Making it far more useful.
Removed Listing Merge routines out of main program and into a
separate application, which is called by CDPlay when needed.

Version 1.04 Wed 15th January 1997
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Fixed problem with wrong Sprites file being loaded for the current 
mode.
Added code to listing save routines to reduce chance of corrupted 
listing files.
Add check to make sure Random play doesn't play the same track 
twice in a row.

Version 1.05 Sun 19th January 1997
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Added Menu, removed Info, Choices etc. buttons from main window
to the menu.
Added volume bar.
Added Auto Repeat CD option in the Choices Window.
Tidied up the code slightly.
Hopefully fixed problem which resulted in CDPlay crashing when using
the Alsystems CDFS drivers.

Version 1.06 Tue 11th February 1997
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Changed Track Playing routines.
Altered the code which generated track time and CD playing time.
Made sure the menu closed if the window was closed, unless adjust used.
Added changing of icon background colour when got input focus.
Added scrolling of window to keep caret in view.
Changed the Volume bar code, so it doesn't mess up as much on a system
which doesn't support it.

Version 1.07 Sat 1st March 1997
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Removed configuration code and turned it into a separate application.
Added new configuration options :
  Disable CD Scanning
  Warn If Track listings Not Saved
  CDMatching Offset Number
  Show Track Lengths
  Added 2 new Time Formats
  Save Volume On Exit
  Auto Save CD Listing
  Changing of the Hotkey Code
Wimpslot was increased to 52K :(

Version 1.08 Tue 11th March 1997
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Reduced the wimpslot back down to 48k again :)
Added better support for the auto save CD listings.
Changed the volume support detection routines.  Hopefully
will work slightly better now.
Rewrote the Help file to cover the new Choices application
Changed the layout of the Choices file so I could remove some
code.
  
Version 1.09 Tue 18th March 1997
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Added two new configuration options to handle problems with
some CDFS drivers.
Fixed a bug that was causing CDPlay to crash occasionally when
redrawing the volume bar.
Changed code so it displays 'CD Scanning Disabled' instead of
'Unknown' for the CD Title when that option is turned on.

Version 1.10 Thu 20th March 1997
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Changed code so track names are empty if they are unknown
Rewrote the Listings file merging program so it is more memory
based processing.  Speeding it up considerable on larger files.
Added a proper sprite for the Misc icon in the Choices program.
Decided to release it if no bugs had crept in :)
   
----------------------------------------------------------------

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 with the possible exception
of the Choices and Listing files.

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

Thanks go to my beta testers for helping to find bugs,
suggesting improvements and generally forcing me to make
it into a releasable product, rather than the underdeveloped
version that I was quite happy with at the time ;)

Thanks also go to Acorn's !CDPlayer whose large memory usage
and lack of functions compelled me into writing this
program in the first place.

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

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

L P T White
208 New Road
West Parley
Ferndown
Dorset
BH22 8EN

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