MKNoteSender Class Reference

MKNoteSender is an auxilliary class that completes the implementation of MKPerformer. More...

#import <MKNoteSender.h>

List of all members.

Public Member Functions
(id)	- owner
	Returns the MKPerformer (or MKNoteFilter or MKMidi object) that owns the MKNoteSender.
(id)	- disconnect:
	Severs the connection between the MKNoteSender and aNoteReceiver; if the MKNoteReceiver isn't connected, this does nothing.
(BOOL)	- isConnected:
	Returns YES if aNoteReceiver is connected to the MKNoteSender, otherwise returns NO.
(id)	- connect:
	Connects aNoteReceiver to the MKNoteSender; if the argument isn't a MKNoteReceiver, the connection isn't made.
(id)	- squelch
	Disables the MKNoteSender's ability to send receiveNote: to its MKNoteReceivers.
(id)	- unsquelch
	Enables the MKNoteSender ability to send MKNotes, undoing the effect of a previous squelch message.
(BOOL)	- isSquelched
	Returns YES if the MKNoteSender is squelched (its MKNote-sending ability is disabled), otherwise returns NO.
(unsigned)	- connectionCount
	Returns the number of MKNoteReceivers that are connected to the MKNoteSender.
(NSArray *)	- connections
	Creates and returns a NSArray of the MKNoteReceivers that are connected to the MKNoteSender.
(void)	- dealloc
	Disconnects and frees the receiver.
(id)	- init
	Initializes a MKNoteSender that was created through allocFromZone:.
(void)	- disconnectAllReceivers
	Severs the connections between the MKNoteSender and all the MKNoteReceivers it's connected to.
(id)	- sendAndFreeNote:atTime:
	Enqueues, with the appropriate MKConductor, a request for sendAndFreeNote:aNote to be sent to self at time beatsSinceStart, measured in beats from the beginning of the MKConductor's performance.
(id)	- sendAndFreeNote:withDelay:
	Enqueues, with the appropriate Conductor, a request for sendAndFreeNote:aNote to be sent to self after delayTimeInBeats.
(id)	- sendAndFreeNote:
	Sends the message sendNote:aNote to self and then frees aNote.
(void)	- sendNote:atTime:
	Enqueues, with the MKConductor object described below, a request for sendNote:aNote to be sent to self at time beatsSinceStart, measured in beats from the beginning of the MKConductor's performance.
(void)	- sendNote:withDelay:
	Enqueues with aNote's MKConductor, a request for sendNote:aNote to be sent to self after delayTimeInBeats.
(id)	- sendNote:
	Sends the message receiveNote:aNote to the MKNoteReceivers that are connected to the MKNoteSender.
(id)	- copyWithZone:
	This is the same as copy, but the new object is allocated from zone.
Protected Attributes
NSMutableArray *	noteReceivers
BOOL	isSquelched
id	owner

---

Detailed Description

MKNoteSender is an auxilliary class that completes the implementation of MKPerformer.

Instances are created and owned by MKPerformer objects, normally when the MKPerformer itself is created or initialized. A MKNoteSender object performs two functions:

• It's part of the link between a MKPerformer and an MKInstrument. MKNoteSender's connect: method connects a MKNoteSender to a MKNoteReceiver, which is owned by an MKInstrument in much the same way that a MKNoteSender is owned by a MKPerformer. By connecting a MKNoteSender to a MKNoteReceiver, their respective owners are said to be connected. MKNoteReceiver 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.

• MKNoteSender's sendNote: method defines the mechanism by which a MKPerformer relays a MKNote to a set of MKInstruments. When a MKNoteSender receives a sendNote: message, it sends receiveNote: to its connected MKNoteReceivers which, in turn, send realizeNote:fromNoteReceiver: to their owners (MKInstrument objects). You can toggle a MKNoteSender's ability to send MKNotes through the squelch and unsquelch methods; a MKNoteSender won't send receiveNote: messages while it's squelched.

There's a fundamental difference between these two tasks in that while you connect MKNoteSenders to MKNoteReceivers from your application, sending MKNotes is a MKPerformer's responsibility: Subclasses of MKPerformer should invoke sendNote: as part of their implementations of the perform method.

Keep in mind that while you can create MKNoteSenders and add them to MKPerformers through messages sent by your application (a MKNoteSender is added to a MKPerformer through the latter's addNoteSender: method), they're designed to be created and added by the MKPerformers themselves. Before adding your own MKNoteSenders to a MKPerformer, you should check the description of the MKPerformer subclass that you're using to ensure that your MKNoteSenders will be recognized.

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

MKNoteSenders are also created, owned, and used by instances of MKNoteFilter and MKMidi - neither of which are actual MKPerformers - as part of their assumptions of the role of MKPerformer. A MKNoteFilter subclass should send sendNote: to its MKNoteSenders as part of its implementation of realizeNote:fromNoteSender:. It isn't anticipated that MKMidi will be subclassed (at least not to override its sendNote: invocation).

---

Member Function Documentation

- (id) owner

Returns the MKPerformer (or MKNoteFilter or MKMidi object) that owns the MKNoteSender.

Returns:

Returns an id.

See also:

- addNoteSender: (MKPerformer, MKNoteFilter, MKMidi)

- (id) disconnect:

(MKNoteReceiver *)

aNoteReceiver

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

Parameters:

aNoteReceiver

is an MKNoteReceiver instance.

Returns:

Returns self.

See also:

- - disconnectAllReceivers, - - connect:, - - isConnected:, - - connections

- (BOOL) isConnected:

(MKNoteReceiver *)

aNoteReceiver

Returns YES if aNoteReceiver is connected to the MKNoteSender, otherwise returns NO.

Parameters:

aNoteReceiver

is an MKNoteReceiver instance.

Returns:

Returns a BOOL.

See also:

-connect, -- disconnectAllReceivers, -- connections, -- connectionCount,

- (id) connect:

(MKNoteReceiver *)

aNoteReceiver

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

Parameters:

aNoteReceiver

is an MKNoteReceiver instance.

Returns:

Returns self.

See also:

- - disconnect:, - isConnected, - - connections

- (id) squelch

Disables the MKNoteSender's ability to send receiveNote: to its MKNoteReceivers.

While a receiver is squelched it can't send MKNotes.

Returns:

Returns self.

See also:

-isSquelched, -- unsquelch

- (id) unsquelch

Enables the MKNoteSender ability to send MKNotes, undoing the effect of a previous squelch message.

Returns:

Returns self.

See also:

-isSquelched, -- squelch

- (BOOL) isSquelched

Returns YES if the MKNoteSender is squelched (its MKNote-sending ability is disabled), otherwise returns NO.

Returns:

Returns a BOOL.

See also:

-- squelch, -- unsquelch

- (unsigned) connectionCount

Returns the number of MKNoteReceivers that are connected to the MKNoteSender.

Returns:

Returns an unsigned int.

See also:

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

- (NSArray *) connections

Creates and returns a NSArray of the MKNoteReceivers that are connected to the MKNoteSender.

Returns:

Returns an id.

See also:

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

- (void) dealloc

Disconnects and frees the receiver.

You can't free a MKNoteSender that's in the process of sending a MKNote.

- (id) init

Initializes a MKNoteSender that was created through allocFromZone:.

Subclasses should send [super init] when overriding this method. The new MKNoteSender is unsquelched and unowned.

Returns:

Returns self.

- (void) disconnectAllReceivers

Severs the connections between the MKNoteSender and all the MKNoteReceivers it's connected to.

See also:

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

- (id) sendAndFreeNote:		(MKNote *)	aNote
atTime:		(double)	beatsSinceStart

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

See sendNote:atTime: for a description of the MKConductor that's used.

Parameters:

	aNote	is an MKNote instance.
	beatsSinceStart	is a double.

Returns:

Returns self.

See also:

-- sendNote:, -- sendAndFreeNote:, -- sendAndFreeNote:withDelay:

- (id) sendAndFreeNote:		(MKNote *)	aNote
withDelay:		(double)	delayTimeInBeats

Enqueues, with the appropriate Conductor, a request for sendAndFreeNote:aNote to be sent to self after delayTimeInBeats.

See sendNote:atTime: for a description of the MKConductor that's used.

Parameters:

	aNote	is an MKNote instance.
	delayTimeInBeats	is a double.

Returns:

Returns self.

See also:

- - sendNote:, - - sendAndFreeNote:, - - sendAndFreeNote:atTime:,

- (id) sendAndFreeNote:

(MKNote *)

aNote

Sends the message sendNote:aNote to self and then frees aNote.

If the receiver is squelched, aNote isn't sent but it is freed.

Parameters:

aNote

is an MKNote instance.

Returns:

Returns self.

See also:

-- sendNote:, -- sendAndFreeNote:atTime:, -- sendAndFreeNote:withDelay:

- (void) sendNote:		(MKNote *)	aNote
atTime:		(double)	beatsSinceStart

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

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

The request is enqueued with the object that's returned by [aNote conductor]. Normally - if the owner is a MKPerformer

• this is the owner's MKConductor. However, if the owner is a MKNoteFilter, the request is enqueued with the MKConductor of the MKPerformer (or MKMidi) that originally sent aNote into the performance (or the defaultConductor if the MKNoteFilter itself created the MKNote).

  Parameters:

  	aNote	is an MKNote instance.
  	beatsSinceStart	is a double.

  See also:

  -- sendNote:, -- sendNote:withDelay:

- (void) sendNote:		(MKNote *)	aNote
withDelay:		(double)	delayTimeInBeats

Enqueues with aNote's MKConductor, a request for sendNote:aNote to be sent to self after delayTimeInBeats.

See sendNote:atTime: for a description of the MKConductor that's used.

Parameters:

	aNote	is an MKNote instance.
	delayTimeInBeats	is a double, measuring beats from the time this message is received.

See also:

-- sendNote:, -- sendNote:atTime:

- (id) sendNote:

(MKNote *)

aNote

Sends the message receiveNote:aNote to the MKNoteReceivers that are connected to the MKNoteSender.

If the MKNoteSender is squelched, the messages aren't sent. Normally, this method is only invoked by the MKNoteSender's owner.

Parameters:

aNote

is an MKNote instance.

Returns:

Returns self if successfully sent, nil if squelched.

See also:

-- sendAndFreeNote:, -- sendNote:withDelay:, -- sendNote:atTime:

- (id) copyWithZone:

(NSZone *)

zone

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

Parameters:

zone

is a NSZone.

Returns:

Returns an id. Creates and returns a new MKNoteSender with the same connections as the receiver.

See also:

-copy

---

Member Data Documentation

- (NSMutableArray*) noteReceivers [protected]

Array of connected MKNoteReceivers.

- (BOOL) isSquelched [protected]

YES if the object is squelched.

- (id) owner [protected]

MKPerformer (or MKNoteFilter) that owns this object.

---

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

• MKNoteSender.h