ScorePlayer.rtf

This is ScorePlayer.rtf in view mode; [Download] [Up]

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.