MusicKit  0.0.0
MKNoteReceiver.h
00001 /*
00002   $Id$
00003   Defined In: The MusicKit
00004 
00005   Description:
00006     During a MusicKit performance, MKInstrument objects realize MKNotes that
00007     are sent to them from MKPerformer objects.  The MKNoteReceiver class
00008     defines the MKNote-receiving mechanism used by MKInstruments; each
00009     MKNoteReceiver object acts as a MKNote input for an MKInstrument.  Closely
00010     related to MKNoteReceiver is the MKNoteSender class, which defines the
00011     MKNote-sending mechanism used by MKPerformers.  By separating these
00012     mechanisms into distinct classes, any MKInstrument can have multiple
00013     inputs and any MKPerformer, multiple outputs.
00014    
00015     A MKNoteReceiver is added to an MKInstrument through the latter's
00016     addNoteReceiver: method.  While an application can create MKNoteReceivers
00017     and add them to an MKInstrument, this is typically done by the MKInstrument itself
00018     when it's created.  You can retrieve the object to which a MKNoteReceiver has
00019     been added by invoking MKNoteReceiver's owner method.
00020    
00021     To send MKNotes from a MKNoteSender to a MKNoteReceiver, the two objects must be
00022     connected.  This is done through the connect: method:
00023    
00024         [aNoteReceiver connect:aNoteSender]
00025    
00026     Every MKNoteReceiver and MKNoteSender contains a list of connections.  The
00027     connect: method adds either object to the other's list; in other
00028     words, the MKNoteReceiver is added to the MKNoteSender's list and the
00029     MKNoteSender is added to the MKNoteReceiver's list.  Both MKNoteReceiver and
00030     MKNoteSender implement connect: as well as disconnect: and disconnect,
00031     methods used to sever connections.  A MKNoteReceiver can be connected to
00032     any number of MKNoteSenders.  Connections can be established and severed
00033     during a performance.
00034    
00035     The MKNote-receiving mechanism is defined in the receiveNote: method.
00036     When a MKNoteReceiver receives the message receiveNote: it sends the
00037     message realizeNote:fromNoteReceiver: to its owner, with the received
00038     MKNote as the first argument and its own id as the second.  receiveNote:
00039     is automatically invoked when a connected MKNoteSender sends a MKNote.
00040     You can toggle a MKNoteReceiver's MKNote-forwarding capability through the
00041     squelch and unsquelch methods; a MKNoteReceiver ignores the MKNotes it
00042     receives while it's squelched.  A newly created MKNoteReceiver is
00043     unsquelched.
00044    
00045     CF:  MKNoteSender, MKInstrument
00046 
00047   Original Author: David A. Jaffe
00048 
00049   Copyright (c) 1988-1992, NeXT Computer, Inc.
00050   Portions Copyright (c) 1994 NeXT Computer, Inc. and reproduced under license from NeXT
00051   Portions Copyright (c) 1994 Stanford University
00052   Portions Copyright (c) 1999-2001, The MusicKit Project.
00053 */
00054 @class MKInstrument;
00055 @class MKNote;
00056 @class MKNoteSender;
00057 
00112 #ifndef __MK_NoteReceiver_H___
00113 #define __MK_NoteReceiver_H___
00114 
00115 #import <Foundation/Foundation.h>
00116 
00117 @interface MKNoteReceiver: NSObject
00118 {
00120     NSMutableArray *noteSenders;
00122     BOOL isSquelched;
00124     MKInstrument *owner;
00125 
00126 @private
00128     id dataObject;
00129 }
00130  
00136 - owner; 
00137 
00144 - init;
00145 
00149 - (void) dealloc; 
00150 
00158 - disconnect: (MKNoteSender *) aNoteSender; 
00159 
00165 - disconnect; 
00166 
00174 - (BOOL) isConnected: (MKNoteSender *) aNoteSender; 
00175 
00183 - connect: (MKNoteSender *) aNoteSender; 
00184 
00191 - squelch; 
00192 
00199 - unsquelch; 
00200 
00209 - (BOOL) isSquelched; 
00210 
00220 - copyWithZone: (NSZone *) zone; 
00221 
00227 - (unsigned) connectionCount;
00228 
00235 - (NSArray *) connections;
00236 
00251 - receiveNote: (MKNote *) aNote; 
00252 
00275 - receiveNote: (MKNote *) aNote atTime: (double) time;
00276 
00291 - receiveNote: (MKNote *) aNote withDelay: (double) delayTime; 
00292 
00293 /* 
00294     You never send this message directly.  
00295     Should be invoked with NXWriteRootObject(). 
00296     Archives isSquelched and object name, if any. 
00297     Also optionally archives elements of MKNoteSender NSArray and owner using 
00298     NXWriteObjectReference(). 
00299 */
00300 - (void) encodeWithCoder: (NSCoder *) aCoder;
00301 
00302 /* 
00303     You never send this message directly.  
00304     Should be invoked via NXReadObject(). 
00305     See write:. 
00306 */
00307 - (id) initWithCoder: (NSCoder *) aDecoder;
00308 
00309 @end
00310 
00311 @interface MKNoteReceiver(Private)
00312 
00313 - _setOwner: obj;
00314 - (void) _setData: (id) anObj;
00315 - (id) _getData;
00316 
00317 - _connect: (MKNoteSender *) aNoteSender;
00318 - _disconnect: (MKNoteSender *) aNoteSender;
00319 
00320 @end
00321 
00322 #endif