MusicKit  0.0.0
names.h
00001 /*
00002   $Id$
00003   Defined In: The MusicKit
00004 
00005   Description: This file contains various functions having to do with names in the MusicKit 
00006 
00007   Original Author: David Jaffe
00008 
00009   Copyright (c) 1988-1992, NeXT Computer, Inc.
00010   Portions Copyright (c) 1994 NeXT Computer, Inc. and reproduced under license from NeXT
00011   Portions Copyright (c) 1994 Stanford University
00012   Portions Copyright (c) 1999-2005 The MusicKit Project.
00013 */
00014 #ifndef __MK_names_H___
00015 #define __MK_names_H___
00016 #ifndef MK_NAMES_H
00017 #define MK_NAMES_H
00018 
00019  /* MusicKit table management.
00020   *  
00021   * The MusicKit provides a simple naming mechanism.  There are 5
00022   * functions provided for manipulating the name of an object. These are
00023   * declared below.
00024   * 
00025   * Names are primarily used when reading and writing scorefiles. For
00026   * example, when you read a scorefile into a MKScore object, the MKParts that
00027   * are created are given the names used in the file.  Similarly, when
00028   * performing a scorefile with a MKScorefilePerformer, the MKNoteSenders are
00029   * given the part names used in the file.  Envelopes and WaveTables
00030   * created when reading a scorefile are also given names.
00031   * 
00032   * When writing a MKScore which contains MKParts you created in an application,
00033   * you can explicitly give the MKParts names.  If a name you specify is not
00034   * unique, or if you don't specify any name, one will be automatically
00035   * generated (a variant of what you supplied). Similarly, when recording to a 
00036   * scorefile with a MKScorefileWriter, you can explicitly provide part names by 
00037   * naming the corresponding MKNoteReceivers.
00038   * 
00039   * Note that the naming mechanism allows any object, whether or not it is
00040   * in the MusicKit, to be named. In general, it is the Application's 
00041   * responsibility to remove the names before freeing the object. 
00042   * However, as a convenience, the following classes remove the instance name
00043   * when freeing the instance. Copying an object does not copy its name.
00044   * 
00045   * It's illegal to change the name of an object during a performance
00046   * involving a MKScorefileWriter. (Because an object'll get written to the
00047   * file with the wrong name.) 
00048   */
00049 
00073 extern BOOL MKNameObject(NSString * name,id object);
00074 
00094 extern NSString *MKGetObjectName(id object);
00095 
00111 extern id MKRemoveObjectName(id object);
00112 
00128 extern id MKGetNamedObject(NSString *name);
00129 
00150 extern BOOL MKAddGlobalScorefileObject(id object,NSString *name);
00151 
00163 extern id MKGetGlobalScorefileObject(NSString *name);
00164 
00181 extern void MKWritePitchNames(BOOL usePitchNames);
00182 
00194 extern void MKWriteKeyNumNames(BOOL useKeyNums);
00195 
00196 #endif /* MK_NAMES_H */
00197 #endif