Release 0.9b  Copyright ã1993 by Don Yacktman.  All Rights Reserved.

ScorePlayer

INHERITS FROM	Object

DECLARED IN	ScorePlayer.h

CLASS DESCRIPTION

A ScorePlayer is an object designed to facilitate the playback of scorefiles from any generic application, particularly games.

To use a ScorePlayer object in your application, you will need to do the following:

	1.	Include the files ScorePlayer.h and ScorePlayer.m in your project.
	2.	Link in the following libraries in this order:  libsynthpatches.a, libunitgenerators.a, libmusickit.a, and libdsp.a.  You can control-drag the library names in the ProjectBuilder Files window so that they will be included in this order.  These libraries should be before the shared libraries.
	3.	From some type of control object, or in a .nib file, instantiate a ScorePlayer object.  Your application should only have one ScorePlayer object; multiple objects would cause all sorts of problems.
	4.	Load a score into the ScorePlayer via either the - selectFile: or - loadFile methods.
	5.	Send a - play: message to start playback and a - stop: message to stop playback.

That is all that is required!  In fact, all the necessary messages can be sent from a .nib file, as is demonstrated in the sample application which is provided with the ScorePlayer object.

If desired, a delegate may be connected to a ScorePlayer with the - setDelegate: method.  Whenever a score finishes playing through once, the delegate will be sent a - scoreFinishedPlaying message.  It is then up to the delegate to decide what to do.  If there is no delegate, and this method is not overridden, the ScorePlayer will restart playback of the score.  It will loop like this until told to - stop:.  As an example, a delegate or subclass could be used to make the ScorePlayer cycle through a list of scorefiles during playback.  If desired, the delegate can query the ScorePlayer to find out why the score stopped playing by sending a - aborted message.  YES will be returned if a - stop message halted playback and NO is returned otherwise.

All three methods which may be used to load a score file (- loadFile, - readScoreFile:, and - selectFile:) will stop playback to load the file.  If a file was being played when the message was sent, play will be restarted  upon exit by default.  If a new score is not loaded, playback will begin at the start of the currently loaded score file.  If a new file was successfully loaded, then playback will begin at the start of that file.  To override this, a subclass should implement versions of these methods which set aborted to YES and then call the super method.  Alternatively, a delegate could be set up which does not restart playback when a score stops playing.

INSTANCE VARIABLES

Inherited from Object	Class	isa;

Declared in ScorePlayer	id	delegate;
BOOL	aborted;

delegate 	Sent a message when a score finishes playing.

aborted 	Used to tell the difference between a score finishing and a forced abort.

METHOD TYPES

Controlling playback	- aborted
	- play:
- stop:

Modifying the object	- delegate
- init
- setDelegate:

Delegate methods	- scoreFinishedPlaying

Reading files	- loadFile 
- readScoreFile: 
- selectFile: 

INSTANCE METHODS

aborted
- (BOOL) aborted

Returns aborted.  Meant for use by the delegate to find out why it was called.  If playback stopped because a -stop: message was sent, then aborted is YES; it is NO otherwise.  Note that the methods which load new score files will stop playback, but will set aborted to NO as currently implemented.  Therefore, the delegate cannot tell if the score file was interrupted or finished normally.  If this distinction is needed, a subclass of ScorePlayer would be necessary, as described above.

See also - scoreFinishedPlaying

delegate
- delegate

Returns the id of the current delegate.

See also - setDelegate:

init
- init

Initializes the receiver.  You invoke this method when creating a new instance.  A subclass implementation should send [super init] before performing its own initialization.  Returns self.

loadFile
- loadFile

Loads the default score file, the name of which is taken from the user's defaults database.  If there is no entry in the user's defaults database, then the ScorePlayer attempts to load the score /LocalLibrary/Music/Scores/ Examp1.score.  This default is defined at the start of ScorePlayer.m, if you wish to change it.  Returns self.  Whenever a new score file is loaded, it's name is stored in the user's default database as the default score with [NXApp name] as the owner of the default.

See also - readScoreFile:, - selectFile:

play:
- play:sender

Starts playing the currently loaded score.  If the score is already playing, this method does nothing.  If no score is loaded, then nil is returned; otherwise self is returned.

See also - stop:

readScoreFile:
- readScoreFile:(const char *)pathName

Reads the score file given by the full pathname pathName.  Returns self.

See also - loadFile, - selectFile:

scoreFinishedPlaying
- scoreFinishedPlaying

This message is sent whenever a score stops playing.  This happens when the score is finished, when -stop: is sent to the ScorePlayer, or when a new score file is loaded.  This message is forwarded to the delegate if it exists and responds to -scoreFinishedPlaying.  If  there is no delegate, the implementation in ScorePlayer will restart playback immediately.  This allows the ScorePlayer to play the score repeatedly until a -stop: message is sent.  You can override this method or provide a delegate to alter this default behavior.  Returns the return value of the delegate's method or returns self.

See also - stop:

selectFile:
- selectFile:sender

Presents the user with an Open Panel, and then loads the selected file.  Returns self.

See also - loadFile, - readScoreFile:

setDelegate:
- setDelegate:newDelegate

Sets newDelegate as the delegate of the ScorePlayer.  Returns the previous delegate.

See also - delegate, - scoreFinishedPlaying

stop:
- stop:sender

Stops playback of the current score.  If no score is playing, -stop: does nothing.  Returns self.

See also - play:, - scoreFinishedPlaying