MusicKit  0.0.0
MKNoteSender.h
00001 /*
00002   $Id$
00003   Defined In: The MusicKit
00004 
00005   Description:
00006     During a MusicKit performance, MKPerformer objects perform MKNotes by
00007     sending them to one or more MKInstrument objects.  The MKNoteSender class
00008     defines the MKNote-sending mechanism used by MKPerformers; each MKNoteSender
00009     object acts as a MKNote output for a MKPerformer.  Closely related to
00010     MKNoteSender is the MKNoteReceiver class, which defines the MKNote-receiving
00011     mechanism used by MKInstruments.  By separating these mechanisms into
00012     distinct classes, any MKPerformer can have multiple outputs and any
00013     MKInstrument, multiple inputs.
00014 
00015     A MKNoteSender is added to a MKPerformer through the latter's
00016     addNoteSender: method.  While you can create and add MKNoteSenders
00017     yourself, this is typically done automatically by the MKPerformer when
00018     it's created.  You can retrieve the object to which a MKNoteSender has
00019     been added by invoking MKNoteSender'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         [aNoteSender connect: aNoteReceiver]
00025 
00026     Every MKNoteSender and MKNoteReceiver 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 disconnectAllReceivers,
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     MKNoteSender's sendNote: method defines the MKNote-sending mechanism.
00036     When a MKNoteSender receives the message sendNote:aNote, it forwards the
00037     MKNote object argument to its MKNoteReceivers by sending each of them the
00038     message receiveNote:aNote.  sendNote: is invoked when the MKNoteSender's
00039     owner performs (or, for MKNoteFilter, when it realizes) a MKNote.  You can
00040     toggle a MKNoteSender's MKNote-sending capability through the squelch and
00041     unsquelch methods; a MKNoteSender won't send any MKNotes while it's
00042     squelched.  A newly created MKNoteSender is unsquelched.
00043    
00044     CF:  MKNoteReceiver, MKPerformer, MKNoteFilter
00045 
00046   Original Author: David A. Jaffe
00047 
00048   Copyright (c) 1988-1992, NeXT Computer, Inc.
00049   Portions Copyright (c) 1994 NeXT Computer, Inc. and reproduced under license from NeXT
00050   Portions Copyright (c) 1994 Stanford University
00051   Portions Copyright (c) 1999-2001, The MusicKit Project.
00052 */
00053 @class MKNoteReceiver;
00054 @class MKNote;
00055 
00113 #ifndef __MK_NoteSender_H___
00114 #define __MK_NoteSender_H___
00115 
00116 #import <Foundation/Foundation.h>
00117 
00118 @interface MKNoteSender: NSObject
00119 {
00121     NSMutableArray *noteReceivers;
00123     BOOL isSquelched;
00125     id owner;
00126 
00127 @private
00128     id dataObject;
00129     BOOL _ownerIsAPerformer;
00130     short isSending;
00131 }
00132 
00139 - owner; 
00140 
00149 - disconnect: (MKNoteReceiver *) aNoteReceiver; 
00150 
00158 - (BOOL) isConnected: (MKNoteReceiver *) aNoteReceiver; 
00159 
00167 - connect: (MKNoteReceiver *) aNoteReceiver; 
00168 
00177 - squelch; 
00178 
00185 - unsquelch; 
00186 
00193 - (BOOL) isSquelched; 
00194 
00201 - (unsigned) connectionCount;
00202 
00209 - (NSArray *) connections;
00210 
00216 - (void) dealloc; 
00217 
00227 - init;
00228 
00234 - (void) disconnectAllReceivers; 
00235 
00248 - sendAndFreeNote: (MKNote *) aNote atTime: (double) beatsSinceStart;
00249 
00262 - sendAndFreeNote: (MKNote *) aNote withDelay: (double) delayTimeInBeats;
00263 
00273 - sendAndFreeNote: (MKNote *) aNote;
00274 
00294 - (void) sendNote: (MKNote *) aNote atTime: (double) beatsSinceStart; 
00295 
00307 - (void) sendNote: (MKNote *) aNote withDelay: (double) delayTimeInBeats; 
00308 
00320 - sendNote: (MKNote *) aNote; 
00321 
00333 - copyWithZone: (NSZone *) zone; 
00334 
00335 /* 
00336     You never send this message directly.  
00337     Archives isSquelched and object name, if any. 
00338     Also conditionally archives MKNoteReceiver List and owner. 
00339   */
00340 - (void) encodeWithCoder: (NSCoder *) aCoder;
00341 
00342 /* 
00343     You never send this message directly.  
00344     See write:. 
00345   */
00346 - (id) initWithCoder: (NSCoder *) aDecoder;
00347 
00348 @end
00349 
00350 @interface MKNoteSender(Private)
00351 
00352 /* Sets the owner (an MKInstrument or MKNoteFilter). In most cases,
00353    only the owner itself sends this message.
00354    */
00355 - _setOwner: obj;
00356 
00357 /* Facility for associating arbitrary data with a MKNoteSender */
00358 - (void) _setData: (id) anObj;
00359 - (id) _getData;
00360 
00369 - (void) _setPerformer: aPerformer;
00370 
00371 // Connection methods shared between MKNoteSenders and MKNoteReceivers
00372 - _disconnect: (MKNoteReceiver *) aNoteReceiver;
00373 - _connect: (MKNoteReceiver *) aNoteReceiver;
00374 
00375 @end
00376 
00377 #endif