MKFileWriter Class Reference
A MKFileWriter is an MKInstrument that realizes MKNotes by writing them to a file on the disk. An abstract class, MKFileWriter provides common functionality for the MusicKit subclasses such as MKScorefileWriter (currently the only subclass of MKFileWriter). More...
#import <MKFileWriter.h>
Public Member Functions | |
| (id) | - init |
| Initializes the object by setting both stream and filename to NULL. | |
| (id) | - setTimeUnit: |
| Sets the unit in which the object measures time. | |
| (MKTimeUnit) | - timeUnit |
| Returns the unit in which the object measures time, either MK_second, MK_timeTag or MK_beat. | |
| (NSString *) | - fileExtension |
| Returns the file extension used by the object. | |
| (id) | - setFile: |
| Associates the object with the file aName. | |
| (id) | - setStream: |
| Points the object's stream pointer to aStream. | |
| (NSMutableData *) | - stream |
| Returns the object's stream pointer, or NULL if it isn't set. | |
| (id) | - copyWithZone: |
| Creates and returns a copy of the object. | |
| (NSString *) | - file |
| Returns the object's file name, if any. | |
| (id) | - finishFile |
| This can be overridden by a subclass to perform post-performance activities. | |
| (id) | - initializeFile |
| This can be overriden by a subclass to perform file initialization, such as writing a file header. | |
| (id) | - firstNote: |
| You never invoke this method; it's invoked automatically just before the object writes its first MKNote. | |
| (id) | - afterPerformance |
| You never invoke this method; it's invoked automatically just after a performance. | |
| (double) | - timeShift |
| Returns the object's performance time offset, in seconds. | |
| (id) | - setTimeShift: |
| Sets a constant value to be added to MKNotes' times when they are written out to the file. | |
Static Public Member Functions | |
| (NSString *) | + fileExtension |
| Returns the file extension used by the object. | |
Detailed Description
A MKFileWriter is an MKInstrument that realizes MKNotes by writing them to a file on the disk. An abstract class, MKFileWriter provides common functionality for the MusicKit subclasses such as MKScorefileWriter (currently the only subclass of MKFileWriter).A MKFileWriter is associated with a file on disk or a data object, either by the file's name or through an NSMutableData object. If you associate a MKFileWriter with a file name (through the setFile: method) the object opens and closes the file for you: The file is opened for writing when the object first receives the realizeNote: message and closed after the performance. A MKFileWriter remembers its file name between performances, but the file is overwritten each time it's opened.
The setStream: method sets the FileWriter's stream instance variable to the given NSMutableData object. Creating and saving the NSMutableData object is the responsibility of the application. After each performance, stream is set to nil.
The subclass responsibility realizeNote:fromNoteReceiver:, inherited from MKInstrument, is passed on to the MKFileWriter subclasses. Two other methods, initializeFile and finishFile, can be redefined in a subclass, although neither must be. initializeFile is invoked just before the first MKNote is written to the file and should perform any special initialization such as writing a file header. finishFile is invoked after each performance and should perform any post-performance cleanup. The values returned by initializeFile and finishFile are ignored.
Member Function Documentation
| - (id) init |
Initializes the object by setting both stream and filename to NULL.
- Returns:
- Returns an id. You must invoke this method when creating a new instance of MKFileWriter. A subclass implementation should send [super init] before performing its own initialization. The return value is ignored.
| - (id) setTimeUnit: | (MKTimeUnit) | aTimeUnit |
Sets the unit in which the object measures time.
- Parameters:
-
aTimeUnit is a MKTimeUnit.
- Returns:
- Returns an id. aTimeUnit can be MK_second for measurement in seconds, MK_beat for beats or MK_timeTag for the value in the Note's timeTag field. The default is MK_second.
| - (MKTimeUnit) timeUnit |
Returns the unit in which the object measures time, either MK_second, MK_timeTag or MK_beat.
- Returns:
- Returns a MKTimeUnit. The default is MK_second.
| + (NSString *) fileExtension |
Returns the file extension used by the object.
- Returns:
- Returns a NSString. The default implementation returns the value of the fileExtension class method. A subclass can implement this method to allow different default file extensions for different instances.
Reimplemented in MKScorefileWriter, and MKScorefileWriter.
| - (NSString *) fileExtension |
Returns the file extension used by the object.
- Returns:
- Returns a NSString. The default implementation returns the value of the fileExtension class method. A subclass can implement this method to allow different default file extensions for different instances.
Reimplemented in MKScorefileWriter, and MKScorefileWriter.
| - (id) setFile: | (NSString *) | aName |
Associates the object with the file aName.
- Parameters:
-
aName is a NSString.
- Returns:
- Returns an id. The file is opened when the first MKNote is realized (written to the file) and closed at the end of the performance. If the object is already in a performance, this does nothing and returns nil, otherwise returns the object.
Reimplemented in MKScorefileWriter.
| - (id) setStream: | (NSMutableData *) | aStream |
Points the object's stream pointer to aStream.
- Parameters:
-
aStream is an NSMutableData.
- Returns:
- Returns an id. You must open and close the aStream yourself. If the object is already in a performance, this does nothing and returns nil, otherwise returns the object.
Reimplemented in MKScorefileWriter.
| - (NSMutableData *) stream |
Returns the object's stream pointer, or NULL if it isn't set.
- Returns:
- Returns an NSMutableData. The pointer is set to NULL after each performance.
| - (id) copyWithZone: | (NSZone *) | zone |
Creates and returns a copy of the object.
- Parameters:
-
zone is an NSZone.
- Returns:
- Returns an id. The new object's filename and stream instance variables are set to NULL.
Reimplemented from MKInstrument.
Reimplemented in MKScorefileWriter.
| - (NSString *) file |
Returns the object's file name, if any.
- Returns:
- Returns an NSString.
| - (id) finishFile |
This can be overridden by a subclass to perform post-performance activities.
- Returns:
- Returns an id. You never send the finishFile message directly to a MKFileWriter; it's invoked automatically after each performance. The return value is ignored.
Reimplemented in MKScorefileWriter.
| - (id) initializeFile |
This can be overriden by a subclass to perform file initialization, such as writing a file header.
- Returns:
- Returns an id. You never send the initializeFile message directly to a MKFileWriter; it's invoked from the firstNote: method. The return value is ignored.
Reimplemented in MKScorefileWriter.
| - (id) firstNote: | (MKNote *) | aNote |
You never invoke this method; it's invoked automatically just before the object writes its first MKNote.
It opens a stream to the object's filename (if set) and then sends initializeFile to the object.
- Parameters:
-
aNote is an id.
- Returns:
- Returns an id.
Reimplemented from MKInstrument.
| - (id) afterPerformance |
You never invoke this method; it's invoked automatically just after a performance.
- Returns:
- Returns an id. It closes the object's stream (if the object opened it itself in the firstNote: method) and sets it to NULL.
Reimplemented from MKInstrument.
| - (double) timeShift |
Returns the object's performance time offset, in seconds.
- Returns:
- Returns a double.
| - (id) setTimeShift: | (double) | timeShift |
Sets a constant value to be added to MKNotes' times when they are written out to the file.
It's up to the subclass to use this value.
- Parameters:
-
timeShift is a double.
- Returns:
- Returns an id.
The documentation for this class was generated from the following file:
