00001 /* 00002 $Id: MKFilePerformer.h 3449 2009-04-04 16:52:47Z leighsmith $ 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
1.5.6