MKNoteReceiver Class Reference

MKNoteReceiver is an auxilliary class that completes the implementation of MKInstrument. More...

#import <MKNoteReceiver.h>

List of all members.

Public Member Functions
(id)	- owner
	Returns the MKInstrument (or MKMidi object) that owns the MKNoteReceiver.
(id)	- init
	Initializes a MKNoteReceiver that was created through allocFromZone:.
(void)	- dealloc
	Disconnects and frees the receiver.
(id)	- disconnect:
	Severs the connection between the MKNoteReceiver and aNoteSender; if the MKNoteSender isn't connected, this does nothing.
(id)	- disconnect
	Severs the connections between the MKNoteReceiver and all the MKNoteSenders it's connected to.
(BOOL)	- isConnected:
	Returns YES if aNoteSender is connected to the MKNoteReceiver, otherwise returns NO.
(id)	- connect:
	Connects aNoteSender to the MKNoteReceiver; if the argument isn't a MKNoteSender, the connection isn't made.
(id)	- squelch
	Disables the MKNoteReceiver's ability to send realizeNote:fromMKNoteReceiver: messages to its owner.
(id)	- unsquelch
	Enables the MKNoteReceiver's ability to send realizeNote:fromMKNoteReceiver: messages to its owner, undoing the effect of a previous squelch message.
(BOOL)	- isSquelched
	Returns YES if the MKNoteReceiver is squelched, otherwise returns NO.
(id)	- copyWithZone:
	Creates and returns a new MKNoteReceiver with the same connections as the receiver.
(unsigned)	- connectionCount
	Returns the number of MKNoteSenders that are connected to the MKNoteReceiver.
(NSArray *)	- connections
	Creates and returns a NSArray of the MKNoteSenders that are connected to the MKNoteReceiver.
(id)	- receiveNote:
	Sends the message realizeNote:aNote fromMKNoteReceiver:self to the MKNoteReceiver's owner thereby causing aNote to be realized by the receiver's owner.
(id)	- receiveNote:atTime:
	Enqueues, with the MKConductor object described below, a request for receiveNote:aNote to be sent to self at time beatsSinceStart, measured in beats from the beginning of the MKConductor's performance.
(id)	- receiveNote:withDelay:
	Enqueues, with the appropriate MKConductor, a request for receiveNote:aNote to be sent to self after delayTime, measured in beats from the time this message is received.
Protected Attributes
NSMutableArray *	noteSenders
BOOL	isSquelched
MKInstrument *	owner

---

Detailed Description

MKNoteReceiver is an auxilliary class that completes the implementation of MKInstrument.

MKNoteReceiver is an auxilliary class that completes the implementation of MKInstrument. Instances of MKNoteReceiver are owned by MKInstrument objects to provide the following:

• It's part of the link between a MKPerformer and an MKInstrument. MKNoteReceiver's connect: method connects a MKNoteReceiver to a MKNoteSender, which is owned by a MKPerformer in much the same way that a MKNoteReceiver is owned by an MKInstrument. By connecting a MKNoteReceiver to a MKNoteSender, their respective owners are said to be connected. MKNoteSender defines an equivalent connect: method - it doesn't matter which of the two objects is the receiver and which is the argument when sending a connect: message.

• MKNoteReceiver's receiveNote: method defines the mechanism by which an MKInstrument obtains MKNotes. When a MKNoteReceiver receives the receiveNote: message, it forwards the argument (a MKNote object) to its owner by invoking the MKInstrument method realizeNote:fromNoteReceiver:. The receiveNote: method itself is sent when a connected MKNoteSender receives a sendNote: message from its owner; you can also send receiveNote: (or one of its five sister methods) directly to a MKNoteReceiver from your application. You can toggle a MKNoteReceiver's ability to pass MKNotes to its owner through the squelch and unsquelch methods; a MKNoteReceiver won't send realizeNote:fromNoteReceiver: messages while it's squelched.

Unlike MKNoteSenders, which are generally expected to be created by the MKPerformers that own them, MKNoteReceivers can be created either by their owners or by your application. For example, each MKSynthInstrument object creates and adds to itself a single MKNoteReceiver. MKScorefileWriter objects, on the other hand, don't create any MKNoteReceivers; it's left to your application to create and add them. A MKNoteReceiver is created through the new class method and added to an MKInstrument through the latter's addNoteReceiver:.

A MKNoteReceiver can be owned by only one MKInstrument at a time; however, it can be connected to any number of MKNoteSenders. In addition, two different MKNoteReceivers can be connected to the same MKNoteSender. Thus the connections between MKPerformers and MKInstruments can describe an arbitrarily complicated network. To retrieve the MKNoteReceivers that are owned by a particular MKInstrument you invoke the MKInstrument's noteReceiver or noteReceivers method.

MKNoteReceivers are also created, owned, and used by MKMidi objects as part of their assumption of the role of MKInstrument.

---

Member Function Documentation

- (id) owner

Returns the MKInstrument (or MKMidi object) that owns the MKNoteReceiver.

Returns:

Returns an id.

See also:

-addNoteReceiver: (MKInstrument, MKMidi)

- (id) init

Initializes a MKNoteReceiver that was created through allocFromZone:.

Subclass should send [super init] when overriding this method.

Returns:

Returns self.

- (id) disconnect:

(MKNoteSender *)

aNoteSender

Severs the connection between the MKNoteReceiver and aNoteSender; if the MKNoteSender isn't connected, this does nothing.

Parameters:

aNoteSender

is an MKNoteSender instance.

Returns:

Returns self.

See also:

-- disconnect, -- connect:, -- isConnected:, -- connections

- (id) disconnect

Severs the connections between the MKNoteReceiver and all the MKNoteSenders it's connected to.

Returns:

Returns self.

See also:

-- disconnect:, -- connect:, -- isConnected:, -- connections

- (BOOL) isConnected:

(MKNoteSender *)

aNoteSender

Returns YES if aNoteSender is connected to the MKNoteReceiver, otherwise returns NO.

Parameters:

aNoteSender

is an MKNoteSender instance.

Returns:

Returns a BOOL.

See also:

-connect, -- disconnect, -- connections, -- connectionCount

- (id) connect:

(MKNoteSender *)

aNoteSender

Connects aNoteSender to the MKNoteReceiver; if the argument isn't a MKNoteSender, the connection isn't made.

Parameters:

aNoteSender

is an MKNoteSender instance.

Returns:

Returns self.

See also:

-- disconnect:, -isConnected, -- connections

- (id) squelch

Disables the MKNoteReceiver's ability to send realizeNote:fromMKNoteReceiver: messages to its owner.

Returns:

Returns self.

See also:

-isSquelched, -- unsquelch

- (id) unsquelch

Enables the MKNoteReceiver's ability to send realizeNote:fromMKNoteReceiver: messages to its owner, undoing the effect of a previous squelch message.

Returns:

Returns self.

See also:

-isSquelched, -- squelch

- (BOOL) isSquelched

Returns YES if the MKNoteReceiver is squelched, otherwise returns NO.

A squelched MKNoteReceiver won't invoke its owner's realizeNote:fromNoteReceiver: method.

Returns:

Returns a BOOL.

See also:

-- squelch, -- unsquelch

- (id) copyWithZone:

(NSZone *)

zone

Creates and returns a new MKNoteReceiver with the same connections as the receiver.

This is the same as copy, but the new object is allocated from zone.

Parameters:

zone

is a NSZone instance.

Returns:

Returns an id.

See also:

-copy

- (unsigned) connectionCount

Returns the number of MKNoteSenders that are connected to the MKNoteReceiver.

Returns:

Returns an unsigned int.

See also:

-- connect:, -- disconnect:, -isConnected, -- connections

- (NSArray *) connections

Creates and returns a NSArray of the MKNoteSenders that are connected to the MKNoteReceiver.

Returns:

Returns a NSArray instance.

See also:

-- connect:, -- disconnect:, -isConnected

- (id) receiveNote:

(MKNote *)

aNote

Sends the message realizeNote:aNote fromMKNoteReceiver:self to the MKNoteReceiver's owner thereby causing aNote to be realized by the receiver's owner.

Parameters:

aNote

is an MKNote instance.

Returns:

Returns the receiver, or nil if the receiver is squelched. If the MKNoteReceiver is squelched, the message isn't sent. This method is invoked automatically as the MKNoteReceiver's connected MKNoteSenders receive sendNote: messages; you can also invoke this method directly, although typically receiveNote: is sent as part of a MKNoteSender's sendNote: method.

See also:

- receiveAndFreeNote:, - - receiveNote:withDelay:, - - receiveNote:atTime:

- (id) receiveNote:		(MKNote *)	aNote
atTime:		(double)	time

Enqueues, with the MKConductor object described below, a request for receiveNote:aNote to be sent to self at time beatsSinceStart, measured in beats from the beginning of the MKConductor's performance.

Parameters:

	aNote	is an MKNote instance.
	time	is a double.

Returns:

Returns self. If beatsSinceStart has already passed, the enqueued message is sent immediately. Returns self.

The request is enqueued with the object that's returned by [aNote conductor]. If the MKNote was received from a MKNoteSender, this is the MKConductor of the MKPerformer that originally sent aNote into the performance. If you invoke this method (or any of the receiveNote: methods that enqueue a message request) directly, or if MKMidi is the originator of the MKNote, then the defaultConductor is used.

See also:

- - receiveNote:,- - receiveNote:withDelay:

- (id) receiveNote:		(MKNote *)	aNote
withDelay:		(double)	delayTime

Enqueues, with the appropriate MKConductor, a request for receiveNote:aNote to be sent to self after delayTime, measured in beats from the time this message is received.

Parameters:

	aNote	is an MKNote instance.
	delayTime	is a double.

Returns:

Returns self. See receiveNote:atTime: for a description of the MKConductor that's used. Returns self.

See also:

- - receiveNote:,- - receiveNote:atTime:

---

Member Data Documentation

- (NSMutableArray*) noteSenders [protected]

Array of connected MKNoteSenders.

- (BOOL) isSquelched [protected]

YES if the object is currently squelched.

- (MKInstrument*) owner [protected]

MKInstrument that owns MKNoteReceiver.

---

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

• MKNoteReceiver.h