MusicKit  0.0.0
MKFilePerformer.h
00001 /*
00002   $Id$  
00003   Defined In: The MusicKit
00004 
00005   Description:
00006     A MKFilePerformer reads data from a file on the disk,
00007     fashions a MKNote object from the data, and then performs
00008     the MKNote.  An abstract superclass, MKFilePerformer
00009     provides common functionality and declares subclass responsibilities
00010     for the subclasses MKMidifilePerformer and MKScorefilePerformer.
00011 
00012     Note: In release 1.0, MKMidifilePerformer is not provided. Use a MKScore object
00013     to read a Midifile.
00014 
00015     A MKFilePerformer is associated with a file, either by the
00016     file's name or with a file pointer.  If you assoicate
00017     a MKFilePerformer with a file name (through the setFile:
00018     method) the object will take care of opening and closing
00019     the file for you:  the file is opened for reading when the
00020     MKFilePerformer receives the activate message and closed when
00021     it receives deactivate.
00022 
00023     The setStream: method associates a MKFilePerformer with a file
00024     pointer.  In this case, opening and closing the file
00025     is the responsibility of the application.  The MKFilePerformer's
00026     file pointer is set to NULL after each performance
00027     so you must send another setStream: message in order to replay the file.
00028 
00029     Note:  The argument to -setStream: is a NSData or NSMutableData.
00030 
00031     The MKFilePerformer class declares two methods as subclass responsibilities:
00032     nextNote and performNote:. nextNote must be subclassed to access the next line of information
00033     from the file and from it create either a MKNote object or a
00034     time value.  It returns the MKNote that it creates, or, in the case of a time value,
00035     it sets the instance variable fileTime to represent the current time in the file
00036     and returns nil.
00037 
00038     The MKNote created by nextNote is passed as the argument
00039     to performNote: which is responsible for performing any manipulations on the
00040     MKNote and then sending it by invoking sendNote:.
00041     The return value of performNote: is disregarded.
00042 
00043     Both nextNote and performNote: are invoked
00044     by the perform method, which, recall from the MKPerformer
00045     class, is itself never called directly but is sent by a MKConductor.
00046     perform also checks and incorporates the time limit
00047     and performance offset established by the timing window
00048     variables inherited from MKPerformer; nextNote and
00049     performNote: needn't access nor otherwise be concerned
00050     about these variables.
00051 
00052     Two other methods, initFile and finishFile, can
00053     be redefined by a MKFilePerformer subclass, although neither
00054     must be.  initializeFile is invoked
00055     when the object is activated and should perform any special
00056     initialization such as reading the file's header or magic number.
00057     If initializeFile returns nil, the MKFilePerformer is deactivated.
00058     The default returns the receiver.
00059 
00060     finishFile is invoked when the MKFilePerformer is deactivated
00061     and should perform any post-performance cleanup.  Its return
00062     value is disregarded.
00063 
00064     A MKFilePerformer reads and performs one MKNote at a time.  This
00065     allows efficient performance of arbitrarily large files.
00066     Compare this to the MKScore object which reads and processes the entire file
00067     before performing the first note.  However, unlike the MKScore object,
00068     the MKFilePerformer doesn't allow individual timing control over the
00069     different MKNote streams in the file; the timing window
00070     specifications inherited from MKPerformer are applied to the entire
00071     file.
00072 
00073     Any number of MKFilePerformers can perform the same file concurrently.
00074 
00075   Original Author: David A. Jaffe
00076 
00077   Copyright (c) 1988-1992, NeXT Computer, Inc.
00078   Portions Copyright (c) 1994 NeXT Computer, Inc. and reproduced under license from NeXT
00079   Portions Copyright (c) 1994 Stanford University.
00080   Portions Copyright (c) 1999-2001, The MusicKit Project.
00081 */
00121 #ifndef __MK_FilePerformer_H___
00122 #define __MK_FilePerformer_H___
00123 
00124 #import <Foundation/Foundation.h>
00125 
00126 #import "MKPerformer.h"
00127 
00128 @interface MKFilePerformer : MKPerformer
00129 {
00131     NSString *filename;
00133     double fileTime;
00135     id stream;
00137     double firstTimeTag;
00139     double lastTimeTag;
00140 }
00141  
00150 - init;
00151 
00152 - copyWithZone:(NSZone *)zone;
00153 
00163 - setFile: (NSString *) aName;
00164 
00169 - (NSString *) file; 
00170 
00180 - setStream: (id) aStream; // TODO either NSMutableData, or NSData
00181 
00186 - (id) stream; // TODO either NSMutableData, or NSData
00187 
00198 - activateSelf;
00199 
00207 + (NSString *) fileExtension;
00208 
00218 + (NSArray *) fileExtensions;
00219 
00229 - perform; 
00230 
00240 - performNote: (MKNote *) aNote; 
00241 
00251 - (MKNote *) nextNote; 
00252 
00262 - initializeFile;
00263 
00270 - (void) deactivate; 
00271 
00282 - finishFile; 
00283 
00292 - setFirstTimeTag: (double) aTimeTag;
00293 
00302 - setLastTimeTag: (double) aTimeTag; 
00303 
00308 - (double) firstTimeTag; 
00309 
00314 - (double) lastTimeTag;
00315 
00325 - (void) encodeWithCoder: (NSCoder *) aCoder;
00326 
00333 - (id) initWithCoder: (NSCoder *) aDecoder;
00334 
00335 @end
00336 
00337 #endif