MKInstrument Class Reference

MKInstrument is an abstract class that defines the general mechanism for receiving and realizing MKNotes during a MusicKit performance. More...

#import <MKInstrument.h>

Inheritance diagram for MKInstrument:

List of all members.

Public Member Functions
(id)	- realizeNote:fromNoteReceiver:
	You implement this method in a subclass to define the manner in which the subclass realizes MKNotes.
(id)	- firstNote:
	You never invoke this method; it's invoked just before the MKInstrument realizes its first MKNote.
(NSArray *)	- noteReceivers
	Creates and returns an NSArray that contains the MKInstrument's MKNoteReceivers.
(int)	- indexOfNoteReceiver:
	Returns the ordinal index of aNoteReceiver in the MKInstrument's MKNoteReceiver NSArray.
(BOOL)	- isNoteReceiverPresent:
	Returns YES if aNoteReceiver is in the MKInstrument's MKNoteReceiver NSArray.
(id)	- addNoteReceiver:
	Adds aNoteReceiver to the MKInstrument, first removing it from its current MKInstrument, if any.
(id)	- removeNoteReceiver:
	Removes aNoteReceiver from the MKInstrument's MKNoteReceiver NSArray, but neither disconnects the MKNoteReceiver from its connected MKNoteSenders, nor does it free the MKNoteReceiver.
(void)	- dealloc
	Disconnects, removes, and releases ivars.
(id)	- disconnectNoteReceivers
	Disconnects the object's MKNoteReceivers.
(id)	- removeFromPerformance
	Removes the object from the performance by disconnecting its MKNoteReceivers and invokes the -afterPerformance method.
(id)	- removeNoteReceivers
	Removes all the MKInstrument's MKNoteReceivers but neither disconnects nor frees them.
(BOOL)	- inPerformance
	Returns YES if the MKInstrument is in performance.
(id)	- afterPerformance
	You never invoke this method; it's automatically invoked when the performance is finished.
(id)	- copyWithZone:
	Creates and returns a new MKInstrument as a copy of the receiving MKInstrument allocated from zone.
(MKNoteReceiver *)	- noteReceiver
	Returns the first MKNoteReceiver in the MKInstrument's MKNoteReceiver NSArray.
(id)	- allNotesOff
	Immediately stops playing any sounding notes.

---

Detailed Description

MKInstrument is an abstract class that defines the general mechanism for receiving and realizing MKNotes during a MusicKit performance.

An MKInstrument receives MKNotes through its MKNoteReceivers, auxilliary objects that are typically connected to a MKPerformer's MKNoteSenders. The manner in which an MKInstrument realizes MKNotes is defined in its implementation of realizeNote:fromNoteReceiver:. This method is automatically invoked by an MKInstrument's MKNoteReceivers, when such objects receive receiveNote: messages.

An MKInstrument is considered to be in performance from the time that one of its MKNoteReceivers invokes the realizeNote:fromNoteReceiver: method until the MKConductor class receives the finishPerformance message. There are two implications regarding an MKInstrument's involvement in a performance:

• An MKInstrument's firstNote: and afterPerformance methods are invoked as the MKInstrument begins and finishes its performance, respectively. These methods can be implemented in a subclass to provide specialized initialization and post-performance cleanup.

• Some MKInstrument methods can't be invoked during a performance. For example, you can't add or remove MKNoteReceivers while the MKInstrument is performing.

Creating and adding MKNoteReceivers to an MKInstrument object is generally the obligation of the MKInstrument subclass; most subclasses dispose of this duty in their init methods. However, instances of some subclasses are born with no MKNoteReceivers - they expect these objects to be added by your application. You should visit the class description of the MKInstrument subclass that you're using to determine just what sort of varmint you're dealing with.

The MusicKit defines a number of MKInstrument subclasses. Notable among these are: MKSynthInstrument, which synthesizes MKNotes on the DSP; MKPartRecorder adds MKNotes to a designated MKPart; MKScorefileWriter writes them to a scorefile; and MKNoteFilter, an abstract class that acts as a MKNote conduit, altering the MKNotes that it receives before passing them on to other MKInstruments. In addition, the MKMidi class can be used as an MKInstrument to realize MKNotes on an external MIDI synthesizer.

---

Member Function Documentation

- (id) realizeNote:		(MKNote *)	aNote
fromNoteReceiver:		(MKNoteReceiver *)	aNoteReceiver

You implement this method in a subclass to define the manner in which the subclass realizes MKNotes.

Parameters:

	aNote	is an id.
	aNoteReceiver	is an id.

Returns:

Returns an id. aNote is the MKNote that's to be realized; aNoteReceiver is the MKNoteReceiver that received it. The default implementation does nothing; the return value is ignored. Keep in mind that notes must be copied on write or store.

You never invoke this method from your application; it should only be invoked by the MKInstrument's MKNoteReceivers as they are sent receiveNote: messages. Keep in mind that you can send receiveNote: directly to a MKNoteReceiver for diagnostic or other untimed reception purposes.

Reimplemented in MKMixerInstrument, MKPartRecorder, MKScorefileWriter, and MKSynthInstrument.

- (id) firstNote:

(MKNote *)

aNote

You never invoke this method; it's invoked just before the MKInstrument realizes its first MKNote.

Parameters:

aNote

is an id.

Returns:

Returns an id. A subclass can implement this method to perform pre-realization initialization. The argument is the MKNote that the MKInstrument is about to realize; it's provided as a convenience and can be ignored in a subclass implementation. The MKInstrument is considered to be in performance after this method returns. The return value is ignored.

See also:

- - afterPerformance, - - inPerformance

Reimplemented in MKFileWriter, and MKMixerInstrument.

- (NSArray *) noteReceivers

Creates and returns an NSArray that contains the MKInstrument's MKNoteReceivers.

Returns:

Returns an NSArray. The MKNoteReceivers themselves aren't copied.

See also:

- addNoteReceiver, - - noteReceiver, - isNoteReceiverPresent

- (int) indexOfNoteReceiver:

(MKNoteReceiver *)

aNoteReceiver

Returns the ordinal index of aNoteReceiver in the MKInstrument's MKNoteReceiver NSArray.

Parameters:

aNoteReceiver

is an id.

Returns:

Returns an int. Returns -1 if aNoteReceiveris not in the NSArray.

- (BOOL) isNoteReceiverPresent:

(MKNoteReceiver *)

aNoteReceiver

Returns YES if aNoteReceiver is in the MKInstrument's MKNoteReceiver NSArray.

Parameters:

aNoteReceiver

is an MKNoteReceiver.

Returns:

Returns a BOOL. Otherwise returns NO.

See also:

- - noteReceiver, - - noteReceivers

- (id) addNoteReceiver:

(MKNoteReceiver *)

aNoteReceiver

Adds aNoteReceiver to the MKInstrument, first removing it from its current MKInstrument, if any.

Parameters:

aNoteReceiver

is an id.

Returns:

Returns an id. If the receiving MKInstrument is in performance, this does nothing and returns nil, otherwise returns aNoteReceiver.

See also:

- - removeNoteReceiver:, - - noteReceivers, - - isNoteReceiverPresent:

- (id) removeNoteReceiver:

(MKNoteReceiver *)

aNoteReceiver

Removes aNoteReceiver from the MKInstrument's MKNoteReceiver NSArray, but neither disconnects the MKNoteReceiver from its connected MKNoteSenders, nor does it free the MKNoteReceiver.

Parameters:

aNoteReceiver

is an id.

Returns:

Returns an id. If the MKInstrument is in performance, this does nothing and returns nil, otherwise returns aNoteReceiver.

See also:

- - removeNoteReceivers, - addNoteReceiver, - - noteReceivers, - isNoteReceiverPresent

- (void) dealloc

Disconnects, removes, and releases ivars.

If the receiver is in performance, does not release the MKInstrument's MKNoteReceivers.

See also:

- - removeNoteReceivers:

Reimplemented in MKMixerInstrument, and MKNoteFilter.

- (id) disconnectNoteReceivers

Disconnects the object's MKNoteReceivers.

Returns:

Returns an id.

- (id) removeFromPerformance

Removes the object from the performance by disconnecting its MKNoteReceivers and invokes the -afterPerformance method.

Returns:

Returns an id. This method is needed in order to be able to free a MKNoteFilter or MKInstrument during a performance. If the receiver is not in performance, does nothing and returns nil.

- (id) removeNoteReceivers

Removes all the MKInstrument's MKNoteReceivers but neither disconnects nor frees them.

Returns:

Returns self.

See also:

- removeNoteReceiver, - addNoteReceiver, - - noteReceivers, - isNoteReceiverPresent

- (BOOL) inPerformance

Returns YES if the MKInstrument is in performance.

Returns:

Returns a BOOL. Otherwise returns NO. An MKInstrument is considered to be in performance from the time that one of its MKNoteReceivers invokes realizNote:fromNoteReceiver:, until the time that the MKConductor class receives finishPerformance.

See also:

- - firstNote:, - - afterPerformance

- (id) afterPerformance

You never invoke this method; it's automatically invoked when the performance is finished.

Returns:

Returns an id. A subclass can implement this method to do post-performance cleanup. The default implementation does nothing; the return value is ignored.

See also:

- - firstNote:, - - inPerformance

Reimplemented in MKFileWriter, and MKMixerInstrument.

- (id) copyWithZone:

(NSZone *)

zone

Creates and returns a new MKInstrument as a copy of the receiving MKInstrument allocated from zone.

Parameters:

zone

is a NSZone.

Returns:

Returns an id. The new object has its own MKNoteReceiver collection that contains copies of the MKInstrument's MKNoteReceivers. The new MKNoteReceivers' connections (see the MKNoteReceiver class) are copied from the MKNoteReceivers in the receiving MKInstrument.

Reimplemented in MKFileWriter, MKNoteFilter, MKPartRecorder, MKScorefileWriter, and MKSynthInstrument.

- (MKNoteReceiver *) noteReceiver

Returns the first MKNoteReceiver in the MKInstrument's MKNoteReceiver NSArray.

Returns:

Returns an MKNoteReceiver. This is useful if you want to send a MKNote directly to an MKInstrument, but you don't care which MKNoteReceiver does the receiving:

[[anInstrument noteReceiver] receiveNote: aNote]

If there are currently no MKNoteReceivers, this method creates and adds a MKNoteReceiver.

See also:

- addNoteReceiver, - - noteReceivers, - isNoteReceiverPresent

- (id) allNotesOff

Immediately stops playing any sounding notes.

The default behaviour is to do nothing. Subclasses may implement specific behaviour appropriate to the synthesis method.

Reimplemented in MKSynthInstrument.

---

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

• MKInstrument.h