----------------------------------------------------
CONTENTS
          


                Copyright 1998,1999,2000 Joakim Hgberg


                V0.97b  2000-03-09
                       
        
                -INTRODUCTION
                -INSTALL
                -MANUAL
                -ALERT WINDOWS
                -POPUP-MENUS
                -SHAREWARE
                -COMPATIBILITY
                -HISTORY
        



        
----------------------------------------------------------------------------
INTRODUCTION

hEARCoach is a heartrainer, a program that will help you improve your 
ability to hear intervals and chords.
                                                             
My intentions are that this program shall be a 100% clean written GEM-
application that will work equally well with TOS, N.AES, GENEVA and 
MagiC but I can't be 100% sure there are no bugs left.
Therefore I must point out that if and when you use this program, you 
do so entirely at your own risk.

This program is NOT in any way based on Flying Dialogs, and this is the
reason why hEARCoach has been under development for quite some time. 
The GEM-library used is made by me alone, and allows non-modal 
window handling and inputs in windows that are untopped.   
There are also two routines for popups, one regular (uses only GEM) 
and one with scrolling possibilities. (uses GEM and VDI-output)


I would like to say THANKS to the people that have helped
me when writing this program. So... ..thanks! 

                hEARCoach supports:

                --> ST-GUIDE ONLINE HELP
                --> BUBBLEGEM
                --> ICONIFY
                --> AP_TERM
                --> GLOBAL WINDOW CYCLING
                --> MIDI-out    (Playing interval/chord)                
                --> MIDI-in     (Answer through MIDI)
                --> Internal sound (Will soon use DMA)
                --> Inputs in background windows   


NOTE: Apologies if my bad english ruins your day!
                                         

---------------------------------------------------------------------------
THANKS

The following people have given me help, advice or bug reports (mostly via 
comp.sys.atari.st.programming), or I have been learning from their source
code or manuals. Since this is my very first program, their help has 
been very valuable!

Help through mail/news:

        Thomas Binder           
        Jo Even Skarstein       
        Guy Harrison            
        Katherine Ellis         
        Louis Holleman          
        Pascal Ricard
        Bo Leuf
        Danny from Electronic Cow
        Ulrich Kaiser
        Johan Klockars
        Lonny Pursell
        
Help through existing material:

        Gregor Duchalski
        Gunther Naumann
        Anthony Jacques
        David Reitter
        Han Kampen

Thanks also goes to:

        Joe Connor
        Bengy Collins   
        Mark Wherry
        Derek Johnson

-Thank you all!


----------------------------------------------------------------------------
INSTALL

To install hEARCoach you really don't have to do much!
Just place these files in the same directory:


Required:

CCH_97B.PRG     The executable program file
CCH_97B.RSC     Resource file for older AES
CCHA97B.RSC     Resource file for newer AES

NOTE: If you have an AES that can handle colour icons then you should 
rename CCHA97B.RSC into CCH_97B. (First make sure to either delete or 
rename the standard RSC!) 
             


Optional:

DEFAULT.CNF     Default config file.
DEFAULT.CRD     Default chords. The chord trainer needs this to work!
COACH.HYP       Manual in HYP-format (For online help through ST-Guide) 
README.TXT      Manual in TXT-format

-Done!
                                    
                                              

ADDITIONAL ADVICE:

        If you have lost DEFAULT.CNF and find it irritating that 
        hEARCoach keeps asking for it on startup, just save a file by that 
        name and place it in same directory as the program is run from.
        The settings in that file will then be read at start-up.

If you try to use sound on a setup that lacks support for ST-SOUND, 
hEARCoach will object. It is currently not possible to use DMA-sound. 
Also ,do not try to use MIDI-out to playback sound if your computer does
not have a MIDI-port since this *MIGHT* make your computer to freeze!

        If you use MIDI-in to select interval or chord,
        then you will probably want to disable BubbleHELP 
        (or just watch where you leave the mouse pointer)
        to prevent BubbleGEM from disturbing your practice!
         
                        
        
----------------------------------------------------------------------------
MANUAL

To start hEARCoach just double click on CCH_97B.PRG



*How to do the setup business*

--> INTERVAL SETUP
--> GLOBAL SETUP


*Using hEARCoach*


--> INTERVAL TRAINER
--> CHORD TRAINER
--> KEYBOARD SHORTCUTS




-----
INTERVAL TRAINER
 

This is a short description of the functions:


*NEXT*
Now an interval is played, and you're supposed to tell which one. 

NOTE:   If the NEXT button is pressed before you have given the right
        answer (or forced hEARCoach to show which one is right) to
        previous interval, a false answer is registred for it and a
        new one is then played.
 

*PLAY*
If you want to hear the interval again, then press PLAY to refresh
your memory as many times you like.


*SHOW*
Will reveal what interval has been played,
but also register a false answer for that interval.


*STATS*
         
Select this and you get a window that shows you how good your answers  
have been so far. You can see for each and every interval how many 
wrong answers answers/attempts there have been. You can also take a look at 
your total overall percentage rate. 

This window is one of the ALERT WINDOWS so you must close it before
you can use any of hEARCoach's other windows.


*Answer through MIDI:*

From v0.96 it is possible to give your answer through a 
MIDI-keyboard. Please note that in "simultanously mode" you are 
supposed to play the lowest note first, but in all other modes you 
must play them strictly in the order they were played! You have to 
hold down the first note until the second one is given.

It is not important in which octave you play the notes, as long as the
interval is the right one! Also, you will be warned if you try 
to enter an interval greater than 11. (Octave + fourth)

NOTE:   Incoming MIDI is always mapped to the current top window!  
        When MIDI-in is enabled and your AES supports live movement 
        of windows you may notice that screen updates are a little bit 
        slower. It will only affect windows that understands MIDI-in!
        
        You can replay latest interval by pressing the damper pedal                              
                             

                        
------
CHORD TRAINER
             
             

You can now (unfortunately only manually) edit the DEFAULT.CRD file that 
keeps the chords used by the chord trainer. 
If this file is not found you will have no chords to practise on!
The chord file will be read every time you open the trainer, so if you 
close the trainer it will forget your latest results.

For now you can use 50 chords at a time and I believe that will be more
than enough for most users. If not, get in touch and I will raise the value! 


*Answer through MIDI:*

Depending on your settings the program will reveal high note/low 
note/root. This can be of help when you want to use a MIDI-keyboard to 
enter the chords. It is not important in which octave you play the 
chord, as long as the chord itself is the right one!

From the popup-menu you can now select which note you want to be 
shown. This is useful as you then can practise in thinking chords from 
more than one point of view. 


               
     
TIP:    To clear the MIDI-buffer and erase the notes you have started 
        to enter through MIDI-in, press the HOLD/DAMPER-pedal. The 
        chord will now be played again.
      

NOTE:   In global setup you have to select a keyrange that will allow 
        all chords to be played, or hEARCoach will object!
        
        Incoming MIDI is mapped to the current top window! 

        If you use the internal sound to play the chord and can only 
        hear one note, then you must select "arpeggio" in GLOBAL 
        SETUP. The internal sound can't at this time play more than 
        one note at a time. Sorry for that.
        
   

-------
KEYBOARD SHORTCUTS


CTRL+I          = Show hEARCoach info 
CTRL+U          = Close window                        
CTRL+Q          = Quit
CTRL+W          = Window cycling (Global cycling if AVSERVER is found)
CTRL+SHIFT+W    = Window cycling (Only hEARCoach windows)
CTRL+SHIFT+U    = Close all windows
CTRL+SHIFT+A    = Uniconify all hEARCoach-windows
CTRL+S          = Save config file
CTRL+L          = Load config file
HELP            = Call ST-GUIDE and view appropriate help-section
RETURN          = Select default in alerts

ARROW-DOWN      = Change default object forward
TAB             = Change default object forward

ARROW UP        = Change default object backwards
TAB+SHIFT       = Change default object backwards

ESC             = Will cancel any alert window/popup-menu



DAMPER PEDAL    = Will clear the MIDI-buffer, and allow you to 
                  start from scratch when entering chords.
                  Any interval or chord recently played
                  will be replayed.                 

                          
-------
INTERVAL SETUP

In this setup dialog you can select which intervals
(from minor second up to perfect eleventh) that are valid, and select
playback mode. Holding the mouse pointer over the buttons will show you
the actual names of the corresponing interval if BubbleGEM is installed
and "help demon" is activated in the CPX. (Won't work with Single-TOS) 

                     

                    



        Following modes are available through the popup-menu:
             
        1* Only up, the intervals lowest note is played first
        2* Only down, the intervals highest note is played first
        3* Simultanously, both notes played at the same time     
        
        4* Up/Down, hEARCoach will either play as 1 or 2
        5* Up/Down/Simul, hEARCoach will either play as 1,2 or 3


(You can also select this by placing mouse over the alternative shown, and 
press left or right mousebutton to scan through all the modes.)
              
NOTE:   Simultanously mode will for now only work in MIDI-mode!
        In sound-mode a regular low-note first will be played instead!

        -This may well change in future releases!


------
GLOBAL SETUP

This is the place to edit how the intervals shall be played.


You have the possibility to select :


*MidiChannel*   (1-16)             
*PrgChange*     (1-127)
*Velocity*      (1-127)
 
(Only for MIDI-device)


*Highest/Lowest note*
The highest/lowest note
that can be played.

      
*Length 1 & 2*
Length in seconds of the two notes.


NOTE:   Length 1 is always corresponding to the first note played,
        and this is not necessarely the lower note!


*Midi/Sound* (TOGGLE)
Select if you want the sound played by your
computer or by an external midi device. I'm 
looking into the problem with the sound option.
The sound provided is indeed *very* bad, but the
program was originally meant only for MIDI-devices.
Still, I'll do my best to find a solution to this!


NOTE:   If you have enabled MIDI-out but haven't got a MIDI-port on your 
        system (eg. if you are running hEARCoach with an emulator 
        your computer most certainly will freeze!

        hEARCoach is at present un-usable on TOSBOX since that 
        emulator doesn't support MIDI or SOUND.
        
        If your computer hasn't got ST-SOUND compatibility you can not 
        use the sound option! (If cookie jar not present ST-SOUND is 
        assumed) A similiar check for MIDI will eventually show up if
        I just can figure out a clean way to do it...  
                                          

*Legato*
If this is selected, the first note won't be
"cut off" when the second note starts to sound. (MIDI only)
                
*AutoNext*
If this is selected, the program will continue
to question you with the next interval if your
previous answer was correct.

*Midi-in*
Select this if you want to use a midi-keyboard to give your answer to 
the interval- or chord-trainer. If so, the interval-trainer will show 
which note that is played first.

-DO NOT ENABLE THIS IN CASE YOUR SYSTEM IS NOT EQUIPPED WITH MIDI-INTERFACE!
 IT *MIGHT* CAUSE YOUR COMPUTER TO FREEZE! BE EXTRA CAREFULLY IF YOU 
 ARE USING MagiC-MAC!


*Arpeggio*
Select this if you want the chord trainer to replay the chords in 
arpeggio mode instead of simultanously.

*Arp.time*
The delay between each note in an arpeggio.
                                
NOTE:   If you press the right mouse button, scanning through the values 
        is carried out quicker!


----------------------------------------------------------------------------
ALERT WINDOWS

(Or "There Can Be Only One")

                  
All alertboxes in hEARCoach are non-modal (except for those warning 
for low RAM-memory left. -For obvious reasons!), which is nice if you're 
running a TOS version with multitasking capabilities. 

Also take a look at the KEYBOARD SHORTCUTS

If you find it strange that the text on the alert buttons sometimes doesn't
read "yes","no" or "ok" it is just because.. ...because...

                  
NOTE:   Be aware of the fact that you must close an alert
        window before you can continue with the program!                        


----------------------------------------------------------------------------
POPUP-MENUS


*Regular menu*

From hEARCoach v0.96 I have implemented a routine for simple 
popup-menus, which at this time can't handle submenus. The routine 
will work fine even if the window containing the popup is untopped.
Also, try operating the menu with arrow up/down and select with return! 

The routine will look differently depending on which AES you have.
With AES<4 it will show a menu similiar to the ones found in menubar, 
with one exception. When selected the menu-item will blink 3 times. 
This is how it works on Mac's. (Note: This does not mean I like 
Macintosh!)                                
             
With AES>=4 the menu will use both 3d-look and action. 
                     


NOTE:   The popup-menu is not working in the same way as
        the alert windows, but is strictly modal!
        Still, ESC can be used to abort it.


----------------------------------------------------------------------------
BUBBLEGEM

The support for BUBBLEGEM is still quite basic and you need to 
activate "help demon" in the BubbleGEM CPX in order to get things to work.
I would also advice you to set the "open time" to about 800 ms. The 
default setting (200ms) is likely to drive you beyond insanity...

Single-TOS users won't be able to get any BubbleGEM-help. It has been 
said by others that the time triggered bubbles will work with WINX but 
I have not verified that myself.

The reason for making the bubbles time triggered is that the right
mouse button still can be used to make inputs in windows in the
background for users of old TOS. If you feel that the bubbles just is
annoying you they can easily be toggled on/off in "general prefs." 
which is found under the menu title "extra"



----------------------------------------------------------------------------
ST-GUIDE ONLINE HELP

If you haven't got ST-GUIDE installed as an accesory, hEARCoach will ask 
AV-SERVER to view the HYP-file (when HELP is called) if you have a 
multitasking OS. By doing this, you don't have to waste RAM on 
ST-GUIDE when it isn't needed. Just be sure to register ST-GUIDE as a 
viewer for HYP-files in THING or whatever AV-SERVER you use. If you 
have one ore more hEARCoach window open when calling ST-GUIDE a help 
section linked to the current hEARCoach top window will be viewed.


*AV-SERVER*

If you have no idea at all what an AV-SERVER is I advise you to read 
through the hypertext for desktop THING. 
 
A multitasking AES and an AV-SERVER is required for global window cycling!
You will need to specify in GEM.CNF (or N_AES.CNF or MINT.CNF) what the 
application name of your AV-SERVER is. If you do not, hEARCoach will search
for THING, and if found it will be used as AV-SERVER. However, make sure 
to setup GEM.CNF properly, or else other applications may not be able 
to handle global window cycling.

In GEM.CNF it might look something like this:
       
        setenv AVSERVER=THING ; or if you prefer the second best ;)
        
        setenv AVSERVER=JINNEE


           
----------------------------------------------------------------------------
SHAREWARE


        -Future development is totally depending on the
         feedback I get from people using this program!
         This release (v0.97b) may well be the last new
         version of hEARCoach as very few people seem to
         be interested in this program.
                                              
         
I have spent quite a lot of time on this program, and expect that people
using it will send me something in return. If you continue to use 
hEARCoach for more than 30 days you really should send me a $3 fee.


3 dollars is not to much, is it? Encourage me to continue the development!
                   
                        
If you wish to send some money:         Joakim Hgberg
(or send me some feedback)              Bodgatan 22
                                        S-931 53  SKELLEFTE
                                        SWEDEN

Email:  gokmase@bigfoot.com
WWW:    http://hem.passagen.se/gokmase/atari



DISCLAIMER: Even if this is a very simple practicing utility, I can't 
be responsible if anything goes wrong with any part of your system. 
When you use this program, you do so at your own risk! However, if you 
encounter problems with hEARCoach, don't hesitate to contact me. 

                  
----------------------------------------------------------------------------
COMPATIBILITY


hEARCoach has been successfully tested with:

- TOS 1.04, 1.62, 2.06  
- Geneva 5, 6             
- oAESis0.76  
- N.AES           
- MagiC/MagiC-PC

Problems have been reported with MagiC-Mac. Some changes have 
been made to fix those problems, but I'm not 100% sure that they have.

If you are a MagiC-Mac owner, please, please, please tell me how 
hEARCoach is doing on your setup. Thanks!


TIP:    hEARCoach will work fine under PaCifiST on the PC. You can
        even enable MIDI-out to replay intervals and chords on a MIDI-
        device if you use the very last version of PaCifiST (0.49b)
  

If you try hEARCoach with another OS-version then please
take the time to notify me of the outcome! 


NOTE:   hEARCoach should since v0.964 no longer
        have problems with high colour resolutions!
        

----------------------------------------------------------------------------
HISTORY


_New in hEARCoach v0.97b         (This release)  2000-03-09_

-Chord trainer improved! Load up to 50 chords through DEFAULT.CRD
-Replay chord or interval by pressing damper pedal
-Various bugfixing
-Various cosmetical changes
-Possible to move background windows when MIDI-in sensitive window is on top
-Improved statistics for the interval trainer
-Better check for specific sound hardware
-BubbleGEM is now supported
-All strings moved to RSC-file (easy to translate!)
-Dialog to set zoom boxes and bubblehelp on/off


_New in hEARCoach v0.964                         1999-08-02_

-Screen buffering has been removed. Increased compatibility.
-Implemented check for sound cookie. If no cookie jar found, or cookie 
jar found but not the right cookie, you can not use sound.
-Removed all fill patterns in all windows (problems without buffering)
-Small changes to MIDI-routines.


_New in hEARCoach v0.963                         1999-07-02_

-Fixed releasing of some forgotten MALLOC:s
-Fixed newly introduced bug in AV-SERVER detection.
-No checking for incoming MIDI (or emptying its buffer)
 if MIDI-in isn't selected 


_New in hEARCoach v0.962                         1999-06-24_

-Small changes to the "select-MIDI-in"-routine
-Fixed a typo
-Filtered out AV-messages when no AV-SERVER is present
 

_New in hEARCoach v0.96                          1999-06-16_

-Various bugfixing
-Possible to give answer through MIDI-in
-Limited support for internal sound in chord trainer
-Improved look-and-feel for newer AES
-New modes available for the interval trainer!
-The mouse position is now tracked, so suitable mouse pointer can be showed
-Simple popup-menu routines implemented (Works fine with any AES!)
-When trying to open a window already existing (& iconified) hEARCoach 
 will move that window to front and uniconify it
-Window positions are saved in the CNF-file
-ESC will abort any open alert window/popup-menu
-TAB causes default object to change. (Same as ARROW-DOWN)
-TAB+SHIFT causes default object to change backwards (Same as ARROW-UP)
-ARROW_UP        = Backwards (Like TAB+SHIFT)
-ARROW-DOWN      = Forward (Like TAB)
-CTRL+A will uniconify all hEARCoach windows
-CTRL+U closes top-window
-CTRL+Q display quit-dialog always
-CTRL+W sent through AVSERVER (if found) to enable global window cycling
 (If no AV-SERVER is useable, this is equal to CTRL+SHIFT+W)
-CTRL+SHIFT+W cycles only hEARCoach windows.
-CTRL+SHIFT+U closes all windows
-CTRL+SHIFT+Q will cause hEARCoach to quit immediately. (Same as AP_TERM)
-AP_TERM is now supported
-Grow/shrinkboxes for ICONIFY/UNICONIFY
-If ST-GUIDE isn't started when needed hEARCoach will ask AVSERVER to do so
-If no AV-SERVER is reported in GEM.CNF, THING will be used
 (If it is present and a multitasking AES is used.)


_New in hEARCoach v0.95b4                        1998-12-18_
       
-No longer possible to open windows if not enough RAM
-Fixed a bug. On window close no MFREE was executed
-hEARCoach now works fine with >256 colors  (Ops! Not true until 0.964)
        
        
_New in hEARCoach v0.95b3                        1998-12-04_

-Remembers path after load or save
-ST-GUIDE now shows appropriate help section when called
-Bugfixing
-Small cosmetical changes

                                        
_New in hEARCoach v0.95b2                        1998-11-23_

-More accurate redraws
-Better stability with ST-GUIDE (No known problems)
-Better stability with GENEVA and N.AES (No known problems)
-Added keyboard shortcuts for LOAD and SAVE, CTRL+L & CTRL+S
-Improved icon redraws and added a temporary icon
-Problems with UNICONIFY under GENEVA is fixed
     

_New in hEARCoach v0.95b                         1998-10-16_

-Beta version of chord trainer (MIDI-only!) added. (At last)
-Improved the keyboard and mouse response under ie. MultiTOS.
-Supports ICONIFY, but still no ICON. 8)
-Supports ST-GUIDE.
-Supports background operations. (Under appropriate AES)
-Grow- and shrinkboxes for all windows.
-General improvements of redraws and such.



