MKPerformer Class Reference

MKPerformer is an abstract class that defines a mechanism for performing MKNotes during a MusicKit performance. More...

#import <MKPerformer.h>

Inheritance diagram for MKPerformer:

List of all members.

Public Member Functions
(NSArray *)	- noteSenders
	Creates and returns a NSArray containing the receiver's MKNoteSenders.
(BOOL)	- isNoteSenderPresent:
	Returns YES if aNoteSender is a member of the receiver's MKNoteSender NSArray.
(id)	- disconnectNoteSenders
	Sends -disconnectAllReceivers to each of the object's MKNoteSenders.
(id)	- releaseNoteSenders
	Disconnects and releases the receiver's MKNoteSenders.
(id)	- removeNoteSenders
	Removes the receiver's MKNoteSenders (but doesn't free them).
(MKNoteSender *)	- noteSender
	Returns the first MKNoteSender in the receiver's NSArray.
(MKNoteSender *)	- removeNoteSender:
	Removes aNoteSender from the receiver.
(MKNoteSender *)	- addNoteSender:
	Adds aNoteSender to the recevier.
(BOOL)	- setConductor:
	Sets the receiver's MKConductor to aConductor.
(MKConductor *)	- conductor
	Returns the receiver's MKConductor.
(id)	- activateSelf
	You never invoke this method directly; it's invoked automatically from the activate method.
(id)	- perform
	This is a subclass responsibility expected to send a MKNote and then set the value of nextPerform.
(id)	- setTimeShift:
	Shifts the receiver's performance time by timeShift beats.
(id)	- setDuration:
	Sets the receiver's maximum performance duration to dur in beats.
(double)	- timeShift
	Returns the receiver's time shift value.
(double)	- duration
	Returns the receiver's duration value.
(int)	- status
	Returns the receiver's status.
(int)	- performCount
	Returns the number of perform messages the receiver has recieved in the current performance.
(id)	- activate
	If the receiver isn't inactive, immediately returns the receiver; if its duration is less than or equal to 0.0, immediately returns nil.
(void)	- deactivate
	If the receiver's status is inactive, this does nothing and immediately returns the receiver.
(id)	- init
	Initializes the receiver.
(id)	- pause
	Suspends the receiver's performance and returns the receiver.
(id)	- pauseFor:
	Like pause, but also enqueues a resume message to be sent the specified number of beats into the future.
(id)	- resume
	Resumes the receiver's performance and returns the receiver.
(id)	- copyWithZone:
	Creates and returns an initialised, inactive MKPerformer as a copy of the receiver.
(double)	- time
	Returns the time, in beats, that the receiver last received the perform message.
(id)	- setFirstTimeTag:
	Implements an informal protocol for firstTimeTag/lastTimeTag.
(id)	- setLastTimeTag:
	Implements an informal protocol for firstTimeTag/lastTimeTag.
(double)	- firstTimeTag
	Returns the first time tag in beats. Returns 0.
(double)	- lastTimeTag
	Returns the last time tag in beats.
(void)	- setDelegate:
	Assigns a delegate to receive messages described in MKPerformerDelegate.h.
(id)	- delegate
	Returns the receiver's delegate, if any.
(id)	- rescheduleBy:
	Shifts the MKPerformer's next scheduled invocation of perform by aTimeIncrement.
(id)	- rescheduleAtTime:
	Shifts the MKPerformer's next scheduled invocation of perform to time, which is in the receiver's MKConductor's time base.
(void)	- encodeWithCoder:
	You never send this message directly.
(id)	- initWithCoder:
	You never send this message directly.
(BOOL)	- inPerformance
	Returns YES if receiver's status is not MK_inactive.
Protected Attributes
MKConductor *	conductor
MKPerformerStatus	status
int	performCount
double	timeShift
double	duration
double	time
double	nextPerform
NSMutableArray *	noteSenders
id	delegate

---

Detailed Description

MKPerformer is an abstract class that defines a mechanism for performing MKNotes during a MusicKit performance.

Each subclass of MKPerformer implements the perform method to define how it obtains and performs MKNotes.

During a performance, a MKPerformer receives a series of perform messages. In its implementation of perform, a MKPerformer subclass must set the nextPerform variable. nextPerform indicates the number of beats to wait before the next perform message is sent. The messages are sent by the MKPerformer's MKConductor. Every MKPerformer is managed by a MKConductor; unless you set its MKConductor explicitly, through the setConductor: method, a MKPerformer is managed by the defaultConductor.

A MKPerformer contains a NSArray of MKNoteSenders, objects that send MKNotes (to MKNoteReceivers) during a performance. MKPerformer subclasses should implement the init method to create and add some number of MKNoteSenders to a newly created instance. As part of its perform method, a MKPerformer typically creates or otherwise obtains a MKNote (for example, by reading it from a MKPart or a scorefile) and sends it by invoking MKNoteSender's sendNote: method.

To use a MKPerformer in a performance, you must first send it the activate message. activate invokes the activateSelf method and then schedules the first perform message request with the MKConductor. activateSelf can be overridden in a subclass to provide further initialization of the MKPerformer. The performance begins when the MKConductor class receives the startPerformance message. It's legal to activate a MKPerformer after the performance has started.

Sending the deactivate message removes the MKPerformer from the performance and invokes the deactivateSelf method. This method can be overridden to implement any necessary finalization, such as freeing contained objects.

During a performance, a MKPerformer can be stopped and restarted by sending it the pause and resume messages, respectively. perform messages destined for a paused MKPerformer are delayed until the object is resumed.

You can shift a MKPerformer's performance timing by setting its timeShift variable. timeShift, measured in beats, is added to the initial setting of nextPerform. If the value of timeShift is negative, the MKPerformer's MKNotes are sent earlier than otherwise expected; this is particularly useful for a MKPerformer that's performing MKNotes starting from the middle of a MKPart or MKScore. A positive timeShift delays the performance of a MKNote.

You can also set a MKPerformer's maximum duration. A MKPerformer is automatically deactivated if its performance extends beyond duration beats.

A MKPerformer has a status, represented as one of the following MKPerformerStatus values:

Status	Meaning
MK_inactive	A deactivated or not-yet-activated MKPerformer.
MK_active	An activated, unpaused MKPerformer.
MK_paused	The MKPerformer is activated but currently paused.

Some messages can only be sent to an inactive (MK_inactive) MKPerformer. A MKPerformer's status can be queried with the status message.

If you subclass MKPerformer, some care is required to make sure that it synchronizes correctly to MIDI time code. To make your own MKPerformer subclass synchronize, you need to support a simple informal protocol called MKPerformer Time Code Protocol, which is described in the next section.

MKPerformer Time Code Protocol

This is an informal protocol, required if a MKPerformer subclass is to synchronize correctly with incoming MIDI time code.

There are three parts to this protocol.

• A Time Code-conforming MKPerformer must implement a method setFirstTimeTag:, which takes a double argument, represnting the starting value of MIDI time code in seconds. A common implementation of this method stores the value it is passed in an instance variable. The MKPerformer class provides a default implementation, which does nothing.

• A Time Code-conforming MKPerformer's activateSelf method must position itself at the MKNote it wants to send at firstTimeTag. If there is no MKNote for that time, it should position itself at the first MKNote following that time. It then sets its nextPerforminstance variable to that MKNote's time (which will be greater than or equal to firstTimeTag.) In other words, it sets nextPerform to the first time it wants to run. Finally, it returns self. If there are no MKNotes to send after the specified time, it returns nil.

• The first invocation of a Time Code-conforming MKPerformer's perform method should send the selected MKNote, then choose the next MKNote and set nextPerform to the time until that MKNote, as usual. You can identify the first invocation because the instance variable performCount will be set to 1. In the first invocation of perform, you may also want to send any noteUpdates that preceed firstTimeTag. This makes sure that all MKSynthInstrument and MIDI controllers are up to date. (This is sometimes called "chasing controller values" in MIDI parlance.)

Here is an example of a simple, but complete, Time Code-conforming MKPerfomer. This example is a simplified version of the MusicKit MKPartPerformer:

#import <MusicKit/MusicKit.h>
#import "MyPartPerformer.h"
@implementation MyPartPerformer: MKPerformer
{
  id part;             // MKPart over which we're sequencing.
  double firstTimeTag; // Required by Time Code Protocol.
  int currentIndex;    // Index of nextNote
}

See also:

MKConductor, MKNoteSender

---

Member Function Documentation

- (NSArray *) noteSenders

Creates and returns a NSArray containing the receiver's MKNoteSenders.

Returns:

Returns an NSArray. The NSArray is autoreleased.

- (BOOL) isNoteSenderPresent:

(MKNoteSender *)

aNoteSender

Returns YES if aNoteSender is a member of the receiver's MKNoteSender NSArray.

Parameters:

aNoteSender

is an id.

Returns:

Returns a BOOL.

- (id) disconnectNoteSenders

Sends -disconnectAllReceivers to each of the object's MKNoteSenders.

Returns:

Returns an id.

- (id) releaseNoteSenders

Disconnects and releases the receiver's MKNoteSenders.

Returns:

Returns the receiver.

- (id) removeNoteSenders

Removes the receiver's MKNoteSenders (but doesn't free them).

Returns:

Returns the receiver.

- (MKNoteSender *) noteSender

Returns the first MKNoteSender in the receiver's NSArray.

Returns:

Returns an id. This is a convenience method provided for MKPerformers that create and add a single MKNoteSender. If there are currently no MKNoteSenders, this method creates and adds a MKNoteSender.

- (MKNoteSender *) removeNoteSender:

(MKNoteSender *)

aNoteSender

Removes aNoteSender from the receiver.

Parameters:

aNoteSender

is an MKNoteSender instance.

Returns:

Returns an id. The receiver must be inactive. If the receiver is currently in performance, or if aNoteSender wasn't part of its MKNoteSender NSArray, returns nil. Otherwise returns aNoteSender. For some subclasses, it is inappropriate for anyone other than the subclass instance itself to send this message. It is illegal to modify an active MKPerformer.

- (MKNoteSender *) addNoteSender:

(MKNoteSender *)

aNoteSender

Adds aNoteSender to the recevier.

Parameters:

aNoteSender

is an MKNoteSender instance.

Returns:

Returns an id. The receiver must be inactive. If the receiver is currently in performance, or if aNoteSender already belongs to the receiver, returns nil. Otherwise returns the receiver.

- (BOOL) setConductor:

(MKConductor *)

aConductor

Sets the receiver's MKConductor to aConductor.

The receiver must be inactive.

Parameters:

aConductor

is an MKConductor instance.

Returns:

Returns an NO if receiver is active, YES if receiver is inactive and MKConductor properly set.

- (MKConductor *) conductor

Returns the receiver's MKConductor.

Returns:

Returns an MKConductor instance.

- (id) activateSelf

You never invoke this method directly; it's invoked automatically from the activate method.

A subclass can implement this method to perform pre-performance activities. In particular, if the subclass needs to alter the initial nextPerform value, it should be done here. If activateSelf returns nil, the receiver is deactivated. The default does nothing and returns the receiver.

Returns:

Returns an id.

Reimplemented in MKFilePerformer, MKMTCPerformer, and MKPartPerformer.

- (id) perform

This is a subclass responsibility expected to send a MKNote and then set the value of nextPerform.

Returns:

Returns an id. The return value is ignored.

Reimplemented in MKFilePerformer, MKMTCPerformer, and MKPartPerformer.

- (id) setTimeShift:

(double)

timeShift

Shifts the receiver's performance time by timeShift beats.

Parameters:

timeShift

is a double.

Returns:

Returns an id. The receiver must be inactive. Returns nil if the receiver is currently in performance, otherwise returns the receiver.

- (id) setDuration:

(double)

dur

Sets the receiver's maximum performance duration to dur in beats.

Parameters:

dur

is a double.

Returns:

Returns an id. The receiver must be inactive. Returns nil if the receiver is currently in performance, otherwise returns the receiver.

- (double) timeShift

Returns the receiver's time shift value.

Returns:

Returns a double.

- (double) duration

Returns the receiver's duration value.

Returns:

Returns a double.

- (int) status

Returns the receiver's status.

Returns:

Returns an int.

- (int) performCount

Returns the number of perform messages the receiver has recieved in the current performance.

Returns:

Returns an int.

- (id) activate

If the receiver isn't inactive, immediately returns the receiver; if its duration is less than or equal to 0.0, immediately returns nil.

Returns:

Returns an id. Otherwise prepares the receiver for a performance by setting nextPerform to 0.0, performCount to 0, invoking activateSelf, scheduling the first perform message request with the MKConductor, and setting the receiver's status to MK_active. If a subclass needs to alter the initial value of nextPerform, it should do so in its implementation of the activateSelf method. Returns the receiver.

- (void) deactivate

If the receiver's status is inactive, this does nothing and immediately returns the receiver.

Otherwise removes the receiver from the performance, invokes deactivateSelf, and sets the receiver's status to MK_inactive. Also sends [delegate hasDeactivated:self]; Returns the receiver.

Reimplemented in MKFilePerformer, MKMTCPerformer, and MKPartPerformer.

- (id) init

Initializes the receiver.

Returns:

Returns an id. You invoke this method when creating a new instance of MKPerformer. A subclass implementation should send [super init] before performing its own initialization.

Reimplemented in MKFilePerformer, MKMTCPerformer, MKPartPerformer, and MKScorefilePerformer.

- (id) pause

Suspends the receiver's performance and returns the receiver.

Returns:

Returns an id. To free a paused MKPerformer during a performance, you should first send it the deactivate message. Also sends [delegate hasPaused:self];

Reimplemented in MKMTCPerformer.

- (id) pauseFor:

(double)

beats

Like pause, but also enqueues a resume message to be sent the specified number of beats into the future.

Parameters:

beats

is a double.

Returns:

Returns an id.

- (id) resume

Resumes the receiver's performance and returns the receiver.

Returns:

Returns an id. Also sends [delegate hasResumed:self];

Reimplemented in MKMTCPerformer.

- (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 in MKFilePerformer, MKPartPerformer, and MKScorefilePerformer.

- (double) time

Returns the time, in beats, that the receiver last received the perform message.

Returns:

Returns a double. If the receiver is inactive, returns MK_ENDOFTIME. The return value is measured from the beginning of the performance and doesn't include any time that the receiver has been paused.

- (id) setFirstTimeTag:

(double)

v

Implements an informal protocol for firstTimeTag/lastTimeTag.

Does nothing in this abstract class.

Reimplemented in MKFilePerformer, MKMTCPerformer, and MKPartPerformer.

- (id) setLastTimeTag:

(double)

v

Implements an informal protocol for firstTimeTag/lastTimeTag.

Does nothing in this abstract class.

Reimplemented in MKFilePerformer, MKMTCPerformer, and MKPartPerformer.

- (double) firstTimeTag

Returns the first time tag in beats. Returns 0.

Returns:

Returns the first time tag in beats.

Reimplemented in MKFilePerformer, MKMTCPerformer, and MKPartPerformer.

- (double) lastTimeTag

Returns the last time tag in beats.

Returns MK_ENDOFTIME.

Returns:

Returns the last time tag in beats.

Reimplemented in MKFilePerformer, MKMTCPerformer, and MKPartPerformer.

- (void) setDelegate:

(id)

object

Assigns a delegate to receive messages described in MKPerformerDelegate.h.

The object is not retained.

Parameters:

object

The receiving delegate object.

- (id) delegate

Returns the receiver's delegate, if any.

Returns:

Returns an id.

- (id) rescheduleBy:

(double)

aTimeIncrement

Shifts the MKPerformer's next scheduled invocation of perform by aTimeIncrement.

Parameters:

aTimeIncrement

is a double.

Returns:

Returns an id. Positive values make the next invocation later, negative values make it earlier. If aTimeIncrement is negative and of a magnitude large enough to shift the MKPerformer into the past, reschedules the MKPerformer to invoke perform immediately.

- (id) rescheduleAtTime:

(double)

aTime

Shifts the MKPerformer's next scheduled invocation of perform to time, which is in the receiver's MKConductor's time base.

Parameters:

aTime

is a double.

Returns:

Returns an id. If time is in the past, reschedules the MKPerformer to invoke performimmediately.

- (void) encodeWithCoder:

(NSCoder *)

aCoder

You never send this message directly.

Archives noteSender array, timeShift, and duration. Also optionally archives conductor and delegate.

Reimplemented in MKFilePerformer, MKPartPerformer, and MKScorefilePerformer.

- (id) initWithCoder:

(NSCoder *)

aDecoder

You never send this message directly.

Note that the status of an unarchived MKPerformer is always MK_inactive.

Reimplemented in MKFilePerformer, MKPartPerformer, and MKScorefilePerformer.

- (BOOL) inPerformance

Returns YES if receiver's status is not MK_inactive.

Returns:

Returns a BOOL.

---

Member Data Documentation

- (MKConductor*) conductor [protected]

The object's MKConductor.

- (MKPerformerStatus) status [protected]

The object's status.

- (int) performCount [protected]

Number of times the object has received perform messages.

- (double) timeShift [protected]

Performance offset time in beats.

- (double) duration [protected]

Maximum performance duration in beats.

- (double) time [protected]

The object's notion of the current time. The time in beats of the current invocation of perform, if any, otherwise, the time in beats of the last invocation of perform.

- (double) nextPerform [protected]

The next time in beats until the object will send a MKNote by sending a perform message.

- (NSMutableArray*) noteSenders [protected]

The object's collection of MKNoteSenders.

- (id) delegate [protected]

The object's delegate, if any.

---

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

• MKPerformer.h