MKFilePerformer Class Reference

During a Music Kit performance, a MKFilePerformer reads and performs time-ordered music data from a file on the disk. An abstract class, MKFilePerformer provides common functionality and declares subclass responsibilities for its one subclass, MKScorefilePerformer. More...

#import <MKFilePerformer.h>

Inheritance diagram for MKFilePerformer:

List of all members.

Public Member Functions
(id)	- init
	Initializes the object by setting stream and filename to NULL.
(id)	- copyWithZone:
	Creates and returns an initialised, inactive MKPerformer as a copy of the receiver.
(id)	- setFile:
	Associates the object with the file named aName.
(NSString *)	- file
	Returns the object's file name, if any.
(id)	- setStream:
	Sets the object's stream to aStream.
(id)	- stream
	Returns the object's encoded stream object, or NULL if it isn't set.
(id)	- activateSelf
	Prepares the object for a performance by opening the associated file (if necessary) and invoking nextNote until it returns an appropriate MKNote - one with a timeTag between firstTimeTag and lastTimeTag, inclusive.
(id)	- perform
	Gets the next MKNote from the object's file by invoking nextNote, passes it as the argument to performNote:, then sets the value of nextPerform.
(id)	- performNote:
	A subclass responsibility expected to manipulate and send aNote, which was presumably just read from a file.
(MKNote *)	- nextNote
	A subclass responsibility expected to fashion a MKNote or timeTag from the file.
(id)	- initializeFile
	A subclass can implement this method to perform file initialization.
(void)	- deactivate
	Invokes finishFile, closes the object's file (if it was set through setFile:), and sets the stream instance variable to nil.
(id)	- finishFile
	A subclass can implement this method for post-performance file operations.
(id)	- setFirstTimeTag:
	Sets the smallest timeTag considered for performance to aTimeTag.
(id)	- setLastTimeTag:
	Sets the largest timeTag considered for performance to aTimeTag.
(double)	- firstTimeTag
	Returns the object's firstTimeTag value.
(double)	- lastTimeTag
	Returns the object's lastTimeTag value.
(void)	- encodeWithCoder:
	You never invoke this method directly; to archive a MKFilePerformer, call the NSArchiver archiveRoot method.
(id)	- initWithCoder:
	You never invoke this method directly; to read an archived MKFilePerformer, call the NSUnarchiver methods.
Static Public Member Functions
(NSString *)	+ fileExtension
	Returns the file name extension that's recognized by the class.
(NSArray *)	+ fileExtensions
	Returns an NSArray of NSStrings holding file extensions that are recognized by the class.
Protected Attributes
NSString *	filename
double	fileTime
id	stream
double	firstTimeTag
double	lastTimeTag

---

Detailed Description

During a Music Kit performance, a MKFilePerformer reads and performs time-ordered music data from a file on the disk. An abstract class, MKFilePerformer provides common functionality and declares subclass responsibilities for its one subclass, MKScorefilePerformer.

A MKFilePerformer is associated with a file either by the file's name or through an NSMutableData instance. If you associate a MKFilePerformer with a file name (through the setFile: method) the object opens and closes the file for you: The file is opened for reading when the MKFilePerformer receives the activate message and closed when it receives deactivate. The setFileStream: method associates a MKFilePerformer with an NSMutableData instance. In this case, opening and closing the file is the responsibility of the application. The MKFilePerformer's stream pointer is set to NULL after each performance so you must send another setFileStream: message in order to replay the file. Any number of MKFilePerformers can perform the same file simultaneously.

The MKFilePerformer class declares two methods as subclass responsibilities: nextNote and performNote:. A subclass implementation of nextNote should be designed to read the next line of information in the file and from it create either a MKNote object or a timeTag value (for the following MKNote). It returns the MKNote that it creates, or, in the case of a timeTag, it sets the instance variable fileTime to represent the current time in the file and returns nil. performNote: should perform any desired manipulations on the MKNote created by nextNote and then pass it as the argument to sendNote: (sent to a MKNoteSender). The value returned by performNote: is ignored.

MKFilePerformer defines two timing variables, firstTimeTag and lastTimeTag. They represent the smallest and largest timeTag values that are considered for performance: MKNotes with timeTags that are less than firstTimeTag are ignored; if nextNote creates a timeTag greater than lastTimeTag, the MKFilePerformer is deactivated.

Creation of a MKFilePerformer's MKNoteSender(s) is a subclass responsibility.

See also:

MKScorefilePerformer, MKPerformer

---

Member Function Documentation

- (id) init

Initializes the object by setting stream and filename to NULL.

You invoke this method when creating a new instance of MKFilePerformer. A subclass implementation should send [super init] before performing its own initialization. The return value is ignored.

Returns:

Returns an id.

Reimplemented from MKPerformer.

Reimplemented in MKScorefilePerformer.

- (id) copyWithZone:

(NSZone *)

zone

Creates and returns an initialised, inactive MKPerformer as a copy of the receiver.

Returns:

Returns an MKPerformer instance. The new object has the same time shift and duration as the reciever. Its time and nextPerform variables are set to 0.0. The new object's MKNoteSenders are copied from the receiver.

Reimplemented from MKPerformer.

Reimplemented in MKScorefilePerformer.

- (id) setFile:

(NSString *)

aName

Associates the object with the file named aName.

The file is opened when the object is activated and closed when its deactivated. If the object is active, does nothing and returns nil, otherwise returns the object.

Parameters:

aName

is a NSString instance.

Returns:

Returns an id.

- (NSString *) file

Returns the object's file name, if any.

Returns:

Returns an NSString.

- (id) setStream:

(id)

aStream

Sets the object's stream to aStream.

The sender must open and close the stream himself. If the object is active, this does nothing and returns nil, otherwise returns the object.

Parameters:

aStream

is an id.

Returns:

Returns an id.

- (id) stream

Returns the object's encoded stream object, or NULL if it isn't set.

Returns:

Returns an id.

- (id) activateSelf

Prepares the object for a performance by opening the associated file (if necessary) and invoking nextNote until it returns an appropriate MKNote - one with a timeTag between firstTimeTag and lastTimeTag, inclusive.

If an appropriate MKNote isn't found, the object is deactivated. You never invoke this method; its invoked by the activate method inherited from MKPerformer.

Returns:

Returns an id.

Reimplemented from MKPerformer.

+ (NSString *) fileExtension

Returns the file name extension that's recognized by the class.

The default implementation returns nil. A subclass may override this method to specify its own file extension.

Returns:

Returns an NSString.

Reimplemented in MKScorefilePerformer.

+ (NSArray *) fileExtensions

Returns an NSArray of NSStrings holding file extensions that are recognized by the class.

The default implementation returns an NSArray whose single element NSString is given the value returned by the fileExtension method. A subclass may override this method to specify its own file extensions.

Returns:

Returns an NSArray.

Reimplemented in MKScorefilePerformer.

- (id) perform

Gets the next MKNote from the object's file by invoking nextNote, passes it as the argument to performNote:, then sets the value of nextPerform.

You never invoke this method; it's invoked by the object's MKConductor. The return value is ignored.

Returns:

Returns an id.

Reimplemented from MKPerformer.

- (id) performNote:

(MKNote *)

aNote

A subclass responsibility expected to manipulate and send aNote, which was presumably just read from a file.

You never invoke this method; it's invoked automatically by the perform method. The return type is ignored.

Parameters:

aNote

is an MKNote instance.

Returns:

Returns an id.

Reimplemented in MKScorefilePerformer.

- (MKNote *) nextNote

A subclass responsibility expected to fashion a MKNote or timeTag from the file.

It should return the MKNote or nil if the next file entry is a timeTag. In the latter case, fileTime should be updated. You never invoke this method; it's invoked automatically by the perform method.

Returns:

Returns an MKNote instance.

Reimplemented in MKScorefilePerformer.

- (id) initializeFile

A subclass can implement this method to perform file initialization.

If nil is returned, the object is deactivated. You never invoke this method; it's invoked automatically by activateSelf. The default implementation does nothing and returns the object.

Returns:

Returns an id.

Reimplemented in MKScorefilePerformer.

- (void) deactivate

Invokes finishFile, closes the object's file (if it was set through setFile:), and sets the stream instance variable to nil.

You never invoke this method; its invoked automatically when the object is deactivated.

Reimplemented from MKPerformer.

- (id) finishFile

A subclass can implement this method for post-performance file operations.

You shouldn't close the stream pointer as part of this method. You never invoke this method; it's invoked automatically by deactivateSelf. The default implementation does nothing. The return value is ignored.

Returns:

Returns an id.

Reimplemented in MKScorefilePerformer.

- (id) setFirstTimeTag:

(double)

aTimeTag

Sets the smallest timeTag considered for performance to aTimeTag.

Returns the object. If the object is active, does nothing and returns nil.

Parameters:

aTimeTag

is a double.

Returns:

Returns an id.

Reimplemented from MKPerformer.

- (id) setLastTimeTag:

(double)

aTimeTag

Sets the largest timeTag considered for performance to aTimeTag.

Returns the object. If the object is active, does nothing and returns nil.

Parameters:

aTimeTag

is a double.

Returns:

Returns an id.

Reimplemented from MKPerformer.

- (double) firstTimeTag

Returns the object's firstTimeTag value.

Returns:

Returns a double.

Reimplemented from MKPerformer.

- (double) lastTimeTag

Returns the object's lastTimeTag value.

Returns:

Returns a double.

Reimplemented from MKPerformer.

- (void) encodeWithCoder:

(NSCoder *)

aCoder

You never invoke this method directly; to archive a MKFilePerformer, call the NSArchiver archiveRoot method.

An archived MKFilePerformer maintains its filename, firstTimeTag, and lastTimeTag instance variables (as well as the instance variables defined in MKPerformer).

Parameters:

aCoder

is an NSCoder instance.

Reimplemented from MKPerformer.

Reimplemented in MKScorefilePerformer.

- (id) initWithCoder:

(NSCoder *)

aDecoder

You never invoke this method directly; to read an archived MKFilePerformer, call the NSUnarchiver methods.

Parameters:

aDecoder

is an NSCoder instance.

Returns:

Returns an id.

Reimplemented from MKPerformer.

Reimplemented in MKScorefilePerformer.

---

Member Data Documentation

- (NSString*) filename [protected]

File name or nil if the file pointer is specifed directly.

- (double) fileTime [protected]

The current time in the file (in beats).

- (id) stream [protected]

Pointer to the MKFilePerformer's file, either NSMutableData or NSData

- (double) firstTimeTag [protected]

The smallest timeTag value considered for performance.

- (double) lastTimeTag [protected]

The greatest timeTag value considered for performance.

---

The documentation for this class was generated from the following file:

• MKFilePerformer.h