MKNote Class Reference

A MKNote object represents a musical sound or event by describing its attributes. More...

#import <MKNote.h>

List of all members.

Public Member Functions

(id) - initWithTimeTag:

Sets timeTag as specified and sets type to mute.

(id) - init

Initializes a MKNote that was created through allocFromZone:.

(void) - dealloc

Removes the receiver from its MKPart, if any, and then frees the receiver and its contents.

(id) - copyWithZone:

Creates and returns a new MKNote object as a copy of the receiver.

(id) - split::

This method splits a noteDur into a noteOn/noteOff pair, as described below.

(MKPerformer *) - performer

Returns the MKPerformer that most recently performed the MKNote.

(MKPart *) - part

Returns the MKPart that contains the MKNote, or nil if none.

(MKConductor *) - conductor

If the MKNote is being sent by a MKPerformer (or MKMidi), returns the MKPerformer's MKConductor.

(void) - setConductor:

Sets conductor instance variable.

(MKPart *) - addToPart:

Removes the MKNote from the MKPart that it's currently a member of and adds it to aPart.

(double) - timeTag

Returns the MKNote's time tag.

(double) - setTimeTag:

Sets the MKNote's time tag to newTimeTag or 0.0, whichever is greater (a time tag can't be negative).

(double) - setTimeTagPreserveEndTime:

Sets the receiver's timeTag to newTimeTag and returns the old timeTag, or MK_ENDOFTIME if none.

(MKPart *) - removeFromPart

Removes the MKNote from its MKPart.

(int) - compare:

Returns a value that indicates which of the receiving MKNote and the argument MKNote would appear first if the two MKNotes were sorted into the same MKPart.

(MKNoteType) - noteType

Returns the MKNote's note type, one of MK_noteDur, MK_noteOn, MK_noteOff, MK_noteUpdate, or MK_mute.

(id) - setNoteType:

Sets the MKNote's note type to newNoteType.

(double) - setDur:

Sets the MKNote's duration to value beats and sets its note type to MK_noteDur.

(double) - dur

If the MKNote has a duration, returns the duration, or MK_NODVAL if it isn't set (use the function MKIsNoDVal() to check for MK_NODVAL).

(double) - setEndTime:

Returns the receiver's old end time (duration + timeTag) and sets duration to newEndTime - timeTag, or MK_NODVAL if not a MK_noteDur or MK_mute.

(double) - endTime

Returns the receiver's end time (duration + timeTag), or MK_NODVAL if not a MK_noteDur or MK_mute.

(int) - noteTag

Return the MKNote's note tag, or MAXINT if it isn't set.

(id) - setNoteTag:

Sets the MKNote's note tag to newTag; if the note type is MK_mute it's changed to MK_noteUpdate.

(id) - removeNoteTag

Removes the noteTag, if any.

(id) - setPar:toDouble:

Sets the value of the parameter identified by parameterTag to aDouble, and sets its data type to MK_double.

(id) - setPar:toInt:

Sets the value of the parameter identified by parameterTag to anInteger, and sets its data type to MK_int.

(id) - setPar:toString:

Sets the value of the parameter identified by parameterTag to aString, and sets its data type to MK_string.

(id) - setPar:toEnvelope:

Sets the value of the parameter identified by parameterTag to anEnvelope, and sets its data type to MK_envelope.

(id) - setPar:toWaveTable:

Sets the value of the parameter identified by parameterTag to aWaveTable, and sets its data type to MK_waveTable.

(id) - setPar:toObject:

Sets the value of the parameter identified by parameterTag to anObject, and sets its data type to MK_object.

(double) - parAsDouble:

Returns a double value converted from the value of the parameter identified by parameterTag.

(int) - parAsInt:

Returns an int value converted from the value of the parameter identified by parameterTag.

(NSString *) - parAsString:

Returns a string converted from a copy of the value of the parameter identified by parameterTag.

(NSString *) - parAsStringNoCopy:

Returns a string converted from a the value of the parameter identified by parameterTag.

(id) - parAsEnvelope:

Returns the MKEnvelope value of parameterTag.

(id) - parAsWaveTable:

Returns the MKWaveTable value of the parameter identified by parameterTag.

(id) - parAsObject:

Returns the object value of the parameter identified by parameterTag.

(BOOL) - isParPresent:

Returns YES if the parameter identified by parameterTag is present in the MKNote (in other words, if its value has been set), and NO if it isn't.

(MKDataType) - parType:

Returns the data type of the value of the parameter identified by parameterTag.

(id) - removePar:

Removes the parameter identified by parameterTag from the MKNote; in other words, this sets the parameter's value to indicate that the parameter isn't set.

(id) - copyParsFrom:

Copies aNote's parameters into the receiving MKNote.

(double) - freq

This method returns the MKNote's frequency, measured in Hertz or cycles-per-second.

(int) - keyNum

This method returns the key number of the MKNote.

(id) - writeScorefileStream:

Writes the MKNote, in scorefile format, to the stream, that is, the data object aStream.

(int) - parVectorCount

Returns the number of parameter bit vectors that the MKNote is using to accommodate all its parameters identifiers.

(unsigned) - parVector:

Returns an integer bit vector that indicates the presence of the index'th set of parameters.

Static Public Member Functions

(int) + parTagForName:

Returns the integer that identifies the parameter named aName.

(NSString *) + parNameForTag:

Returns the name that identifies the parameter tagged aTag.

(id) + note

Allocates and initializes a new MKNote and returns it autoreleased.

(id) + noteWithTimeTag:

Allocates and initializes a new MKNote and returns it autoreleased.

Protected Attributes

MKNoteType noteType

int noteTag

MKPerformer * performer

MKPart * part

double timeTag

MKConductor * conductor

Detailed Description

A MKNote object represents a musical sound or event by describing its attributes.

MKNote objects are containers of musical information. The amount and type of information that a MKNote can hold is practically unlimited; however, you should keep in mind that MKNotes haven't the ability to act on this information, but merely store it. It's left to other objects to read and process the information in a MKNote. Most of the other MusicKit classes are designed around MKNote objects, treating them as common currency. For example, MKPart objects store MKNotes, MKPerformers acquire them and pass them to MKInstruments, MKInstruments read the contents of MKNotes and apply the information therein to particular styles of realization, and so on.

The information that comprises a MKNote defines the attributes of a particular musical event. Typically, an object that uses MKNotes plucks from them just those bits of information in which it's interested. Thus you can create MKNotes that are meaningful in more than one application. For example, a MKNote object that's realized as synthesis on the DSP would contain many particles of information that are used to drive the synthesis machinery; however, this doesn't mean that the MKNote can't also contain graphical information, such as how the MKNote would be rendered when drawn on the screen. The objects that provide the DSP synthesis realization (MKSynthPatch objects, as defined by the MusicKit) are designed to read just those bits of information that have to do with synthesis, and ignore anything else the MKNote contains. Likewise, a notation application would read the attributes that tell it how to render the MKNote graphically, and ignore all else. Of course, some information, such as the pitch and duration of the MKNote, would most likely be read and applied in both applications.

Most of the methods defined by the MKNote class are designed to let you set and retrieve information in the form of parameters. A parameter consists of a tag, a name, a value, and a data type:

A parameter tag is a unique integer used to catalog the parameter within the MKNote; the MusicKit defines a number of parameter tags such as MK_freq (for frequency) and MK_amp (for amplitude).
The parameter's name is used primarily to identify the parameter in a scorefile. The names of the MusicKit parameters are the same as the tag constants, but without the "MK_" prefix. You can also use a parameter's name to retrieve its tag, by passing the name to MKNote's parTagForName: class method. (As explained in its descriptions below, it's through this method that you create your own parameter tags.) Similarly, you can get a name from a tag with MKNote's parNameForTag: class method.
A parameter's value can be a double, int, string (char *), or an object (id). The method you invoke to set a parameter value depends on the type of the value. To set a double value, for example, you would invoke the setPar:toDouble: method. Analogous methods exist for the other types. You can retrieve the value of a double-, int-, or string-valued parameter as any of these three types, regardless of the actual type of the value. For example, you can set the frequency of a MKNote as a double, thus:
[aNote setPar: MK_freq toDouble: 440.0]
and then retrieve it as an int:
int freq = [aNote parAsInt: MK_freq]
The type conversion is done automatically.
Object-valued parameters are treated differently from the other value types. The only MusicKit objects that are designed to be used as parameter values are MKEnvelopes and MKWaveTables (and the MKWaveTable descendants MKPartials and MKSamples). Special methods are provided for setting and retrieving these objects. Other objects, most specifically, objects of your own classes, are set through the setPar:toObject: method. While an instance of any class may be set as a parameter's value through this method, you should note well that only those objects that respond to the writeASCIIStream: and readASCIIstream: messages can be written to and read from a scorefile. None of the MusicKit classes implement these methods and so their instances can't be written to a scorefile as parameter values (MKEnvelopes and MKWaveTables are written and read through a different mechanism).
The parameter's data type is set when the parameter's value is set; thus the data type is either a double, int, string, MKEnvelope, MKWaveTable, or (other) object. These are represented by constants, as given in the description of parType:, the method that retrieves a parameter's data type.

A parameter is said to be present within a MKNote once its value has been set. You can determine whether a parameter is present in one of four ways:

The easiest way is to invoke the boolean method isParPresent:, passing the parameter tag as the argument. An equivalent C function, MKIsNoteParPresent() is also provided for greater efficiency.
At a lower lever, you can invoke the parVector: method to retrieve one of a MKNote's “parameter bit vectors”, integers that the MKNote uses internally to indicate which parameters are present. You query a parameter bit vector by masking it with the parameter's tag:
```
// A MKNote may have more then one bit vector to accommodate all
// its parameters.
```
```
int parVector = [aNote parVector: (MK_amp / 32)];
```
```
// If MK_amp is present, the predicate will be true.
if (parVector & (1 << (MK_amp % 32)))
```
If you plan on retrieving the value of the parameter after you've checked for the parameter's presence, then it's generally more efficient to go ahead and retrieve the value and then determine if the parameter is actually set by comparing its value to the appropriate parameter-not-set value, as given below:

Retrieval type No-set value

int MAXINT

double MK_NODVAL (but see below)

NSString @“”

id nil

Unfortunately, you can't use MK_NODVAL in a simple comparison predicate. To check for this return value, you must call the in-line function MKIsNoDVal(); the function returns 0 if its argument is MK_NODVAL and nonzero if not:
```
// Retrieve the value of the amplitude parameter.
double amp = [aNote parAsDouble: MK_amp];
```
```
// Test for the parameter's existence.
if (!MKIsNoDVal(amp))
  ... // do something with the parameter
```
If you're looking for and processing a large number of parameters in one block, then you should make calls to the MKNextParameter() C function, which returns the values of a MKNote's extant parameters only. See the function's description in Chapter 2 for more details.

A MKNote has two special timing attributes: A MKNote's time tag corresponds, conceptually, to the time during a performance that the MKNote is performed. Time tags are set through the setTimeTag: method. The other timing attribute is the MKNote's duration, a value that indicates how long the MKNote will endure once it has been struck. It's set through setDur:. A single MKNote can have only one time tag and one duration. Keep in mind, however, that not all MKNotes need a time tag and a duration. For example, if you realize a MKNote by sending it directly to an MKInstrument, then the MKNote's time tag - indeed, whether it even has a time tag - is of no consequence; the MKNote's performance time is determined by when the MKInstrument receives it (although see the MKScorefileWriter, MKScoreRecorder, and MKPartRecorder class descriptions for alternatives to this edict). Similarly, a MKNote that merely initiates an event, relying on a subsequent MKNote to halt the festivities, as described in the discussion of note types, below, doesn't need and actually mustn't be given a duration value.

During a performance, time tag and duration values are measured in time units called beats. The size of a beat is determined by the tempo of the MKNote's MKConductor. You can set the MKNote's conductor directory with the method setConductor:. However, if the MKNote is in the process of being sent by a MKPerformer (or MKMidi), the MKPerformer's MKConductor is used instead. Hence, MKNote's conductor method returns the MKPerformer's MKConductor if the MKNote is in the process of being sent by a MKPerformer, or the MKNote's conductor otherwise. If no MKConductor is set, then its MKConductor is the defaultConductor, which has a default (but not immutable) tempo of 60.0 beats per minute.

Keep in mind that if you send a MKNote directly to an MKInstrument, then the MKNote's time tag is (usually) ignored, as described above, but its duration may be considered and employed by the MKInstrument.

A MKNote has a note type that casts it into one of five roles:

A noteDur represents an entire musical note (a note with a duration).
A noteOn establishes the beginning of a note.
A noteOff establishes the end of a note.
A noteUpdate represents the middle of a note (it updates a sounding note).
A mute makes no sound.

Only noteDurs may have duration values; the very act of setting a MKNote's duration changes it to a noteDur.

You match the two MKNotes in a noteOn/noteOff pair by giving them the same note tag value; a note tag is an integer that identifies two or more MKNotes as part of the same musical event or phrase. In addition to coining noteOn/noteOff pairs, note tags are used to associate a noteUpdate with a noteDur or noteOn that's in the process of being performed. The C function MKNoteTag() is provided to generate note tag values that are guaranteed to be unique across your entire application - you should never create a new note tag except through this function.

Instead of or in addition to being actively realized, a MKNote object can be stored. In a running application, MKNotes are stored within MKPart objects through the addToPart: method. A MKNote can only be added to one MKPart at a time; adding it to a MKPart automatically removes it from its previous MKPart. Within a MKPart object, MKNotes are sorted according to their time tag values.

For long-term storage, MKNotes can be written to a scorefile. There are two "safe" ways to write a scorefile: You can add a MKNote-filled MKPart to a MKScore and then write the MKScore to a scorefile, or you can send MKNotes during a performance to a MKScorefileWriter MKInstrument. The former of these two methods is generally easier and more flexible since it's done statically and allows random access to the MKNotes within a MKPart. The latter allows MKNote objects to be reused since the file is written dynamically; it also lets you record interactive performances.

You can also write individual MKNotes in scorefile format to an open stream by sending writeScorefileStream: to the MKNotes. This can be convenient while debugging, but keep in mind, however, that the method is designed primarily for use by MKScore and MKScorefileWriter objects; if you write MKNotes directly to a stream that's open to a file, the file isn't guaranteed to be recognized by methods that read scorefiles, such as MKScore's readScorefile:.

MKNote are automatically created by the MusicKit in a number of circumstances, such as when reading a MKScorefile. The function MKSetNoteClass() allows you to specify that your own subclass of MKNote be used when MKNotes are automatically created. You retrieve the MKNote class with MKGetNoteClass().

Member Function Documentation

- (id) initWithTimeTag: (double) aTimeTag

Sets timeTag as specified and sets type to mute.

Parameters:

aTimeTag

is a double in seconds. If aTimeTag is MK_ENDOFTIME, the timeTag isn't set. Subclasses should send [super initWithTimeTag:aTimeTag] if it overrides this method.

- (id) init

Initializes a MKNote that was created through allocFromZone:.

Returns:: Returns self. For example:

id aNote = [MKNote allocFromZone:aZone]; [aNote init];

A newly initialized MKNote's note type is mute.

Same as [self initWithTimeTag:MK_ENDOFTIME].

See also:: -- init:

- (void) dealloc

Removes the receiver from its MKPart, if any, and then frees the receiver and its contents.

The contents of object-valued, envelope-valued and wavetable-valued parameters aren't freed.

- (id) copyWithZone: (NSZone *) zone

Creates and returns a new MKNote object as a copy of the receiver.

Parameters:

zone

is an NSZone. The receiver's parameters, timing information, noteType, and noteTag are copied into the new MKNote. Object-valued parameters are shared by the two MKNotes. The new MKNote's MKPart is set to nil.

- (id) split:	(id *)	aNoteOn
:	(id *)	aNoteOff

This method splits a noteDur into a noteOn/noteOff pair, as described below.

The new MKNotes are returned by reference in the arguments. The noteDur itself is left unchanged. If the receiving MKNote isn't a noteDur, this does nothing and returns nil, otherwise it returns self.

The receiving MKNote's MK_relVelocity parameter, if present, is copied into the noteOff. All other parameters are copied into (or, in the case of object-valued parameters, referenced by) the noteOn. The noteOn takes the receiving MKNote's time tag value; the noteOff's time tag is that of the MKNote plus its duration. If the receiving MKNote has a note tag, it's copied into the noteOn and noteOff; otherwise a new note tag is generated for them. The new MKNotes are added to the receiving MKNote's MKPart, if any.

Keep in mind that if while this method replicates the noteDur within the noteOn/noteOff pair, it doesn't replace the former with the latter. To do this, you must free the noteDur yourself.

The new MKNotes are returned as retained objects (ie you must release them yourself as they are not autoreleased).

Parameters:

	aNoteOn	is an id *.
	aNoteOff	is an id *.

Returns:: Returns an id.

- (MKPerformer *) performer

Returns the MKPerformer that most recently performed the MKNote.

Returns:: Returns an MKPerformer instance. This is provided, primarily, as part of the implementation of the conductor method.

See also:: -conductor

- (MKPart *) part

Returns the MKPart that contains the MKNote, or nil if none.

Returns:: Returns an MKPart instance. By default, a MKNote isn't contained in a MKPart.

See also:: -- addToPart:, -- removeFromPart

- (MKConductor *) conductor

If the MKNote is being sent by a MKPerformer (or MKMidi), returns the MKPerformer's MKConductor.

Returns:: Returns an MKConductor instance. Otherwise, if conductor was set with setConductor:, returns the conductor instance variable. Otherwise returns the defaultConductor. A MKNote's MKConductor is used, primarily, by MKInstrument objects that split noteDurs into noteOn/noteOff pairs; performance of the noteOff is scheduled with the MKConductor that's returned by this method.

See also:: -performer

- (void) setConductor: (MKConductor *) newConductor

Sets conductor instance variable.

Parameters:

newConductor

is an MKConductor instance. Note that newConductor is not archived, nor is it saved when a MKNote is added to a MKPart - it is used only in performance. Note that -setConductor: is called implicitly when a MKNote is copied with the copy method. Be careful not to release a MKConductor while leaving a dangling reference to it in a MKNote!

See also:: -conductor

- (MKPart *) addToPart: (MKPart *) aPart

Removes the MKNote from the MKPart that it's currently a member of and adds it to aPart.

Parameters:

aPart

is an id.

Returns:: Returns the receiver's old MKPart, if any. This method is equivalent to MKPart's addNote: method.

See also:: -part, -- removeFromPart

- (double) timeTag

Returns the MKNote's time tag.

Returns:: Returns a double. If the time tag isn't set, MK_ENDOFTIME is returned. Time tag values are used to sort the MKNotes within a MKPart.

See also:: -- setTimeTag:

- (double) setTimeTag: (double) newTimeTag

Sets the MKNote's time tag to newTimeTag or 0.0, whichever is greater (a time tag can't be negative).

Parameters:

newTimeTag

is a double.

Returns:: Returns a double. The old time tag value is returned; a return value of MK_ENDOFTIME indicates that the time tag hadn't been set. If newTimeTag is negative, it is clipped to 0.0. Time tags are used to sort the MKNotes within a MKPart; if you change the time tag of a MKNote that's been added to a MKPart, the MKNote is automatically resorted.

See also:: -timeTag, -- addToPart:, -sort (MKPart)

- (double) setTimeTagPreserveEndTime: (double) newTimeTag

Sets the receiver's timeTag to newTimeTag and returns the old timeTag, or MK_ENDOFTIME if none.

Parameters:

newTimeTag

If newTimeTag is negative, it's clipped to 0.0. If newTimeTag is greater than the endTime, it is clipped to endTime.

If the receiver is a member of a MKPart, it's first removed from the MKPart, its timeTag is set, and then it's re-added to the MKPart. This ensures that the receiver's position within its MKPart is correct.

Duration is changed to preserve the endTime of the note

Note: ONLY works for MK_noteDur type notes! MK_NODVAL returned otherwise.

- (MKPart *) removeFromPart

Removes the MKNote from its MKPart.

Returns:: Returns the MKPart, or nil if none.

See also:: -- addToPart:, -part

- (int) compare: (MKNote *) aNote

Returns a value that indicates which of the receiving MKNote and the argument MKNote would appear first if the two MKNotes were sorted into the same MKPart.

The values returned are:

-1 indicates that the receiving MKNote is first.
1 means that the argument, aNote, is first.
0 is returned if the receiving MKNote and aNote are the same object.

If the timeTags are equal, the comparison is by order in the part.

Keep in mind that the two MKNotes needn't actually be members of the same MKPart, nor must they be members of MKParts at all. Naturally, the comparison is judged first on the relative values of the two MKNotes' time tags; changing one or both of the MKNotes' time tags invalidates the result of a previous invocation of this method.

Parameters:

aNote

is an MKNote instance.

Returns:: Returns an int.

- (MKNoteType) noteType

Returns the MKNote's note type, one of MK_noteDur, MK_noteOn, MK_noteOff, MK_noteUpdate, or MK_mute.

Returns:: Returns a MKNoteType. The note type describes the character of the MKNote, whether it represents an entire musical note (or event), the beginning, middle, or end of a note, or no note (no sound). A newly created MKNote is a mute. A MKNote's note type can be set through setNoteType:, although setDur: and setNoteTag: may also change it as a side effect.

See also:: -- setNoteType:, -- setDur:, -- setNoteTag:

- (id) setNoteType: (MKNoteType) newNoteType

Sets the MKNote's note type to newNoteType.

Parameters:

newNoteType

is a MKNoteType.

Returns:: Returns self, or nil if newNoteType isn't a valid note type. The note type can be one of:

MK_noteDur; represents an entire musical note.
MK_noteOn; represents the beginning of a note.
MK_noteOff; represents the end of a note.
MK_noteUpdate; represents the middle of a note.
MK_mute; makes no sound.

You should keep in mind that the setDur: method automatically sets a MKNote's note type to MK_noteDur; setNoteTag: changes mutes into noteUpdates.

See also:: -noteType, -- setNoteTag:, -- setDur:

- (double) setDur: (double) value

Sets the MKNote's duration to value beats and sets its note type to MK_noteDur.

Parameters:

value

is a double.

Returns:: Returns a double. If value is negative the duration isn't set, the note type isn't changed, and MK_NODVAL is returned (use the function MKIsNoDVal() to check for MK_NODVAL); otherwise returns value.

See also:: -- dur, -conductor

- (double) dur

If the MKNote has a duration, returns the duration, or MK_NODVAL if it isn't set (use the function MKIsNoDVal() to check for MK_NODVAL).

Returns:: Returns a double. This method always returns MK_NODVAL for noteOn, noteOff and noteUpdate MKNotes. It returns a valid dur (if one has been set) for noteDur MKNotes. For mute MKNotes, it returns a valid value if the MKNote has an MK_restDur parameter, otherwise it returns MK_NODVAL. This allows you to specify rests with durations.

See also:: -- setDur:

- (int) noteTag

Return the MKNote's note tag, or MAXINT if it isn't set.

Returns:: Returns an int.

See also:: -- setNoteTag:, MKNoteTag()

- (id) setNoteTag: (int) newTag

Sets the MKNote's note tag to newTag; if the note type is MK_mute it's changed to MK_noteUpdate.

Parameters:

newTag

is an int.

Returns:: Returns self. MKNote tags are used to associate different MKNotes with each other, thus creating an identifiable (by the note tag value) "Note stream." For example, you create a noteOn/noteOff pair by giving the two MKNotes identical note tag values. Also, you can associate any number of noteUpdates with a single noteDur, or with a noteOn/noteOff pair, through similarly matching note tags. While note tag values are arbitrary, they should be unique across an entire application; to ensure this, you should never create noteTag values but through the MKNoteTag() C function.

See also:: -noteTag, MKNoteTag()

- (id) removeNoteTag

Removes the noteTag, if any.

Returns:: Returns an id. Same as [self setNoteTag:MAXINT].

+ (int) parTagForName: (NSString *) aName

Returns the integer that identifies the parameter named aName.

Parameters:

aName

is a NSString.

Returns:: Returns an int. If the named parameter doesn't have an identifier, one is created and thereafter associated with the parameter.

See also:: -- setPar:toDouble:(etc), -- isParPresent:, -+ parNameForTag:

+ (NSString *) parNameForTag: (int) aTag

Returns the name that identifies the parameter tagged aTag.

For example [MKNote parNameForTag: MK_freq] returns "freq". If the parameter number given is not a valid parameter number, returns an empty string. Note that the string is not copied.

Parameters:

aTag

is an int.

Returns:: Returns a NSString.

See also:: -- setPar:toDouble:(etc), -- isParPresent:, -+ parNameForTag:

- (id) setPar:	(int)	parameterTag
toDouble:	(double)	aDouble

Sets the value of the parameter identified by parameterTag to aDouble, and sets its data type to MK_double.

If aDouble is the special value MK_NODVAL, this method is the same as [self removePar: parameterTag].

Parameters:

	parameterTag	is an int.
	aDouble	is a double.

Returns:: Returns self.

See also:: ++ parTagForName:, ++ parNameForTag:, -- parType:, -- isParPresent:, -- parAsDouble:

- (id) setPar:	(int)	parameterTag
toInt:	(int)	anInteger

Sets the value of the parameter identified by parameterTag to anInteger, and sets its data type to MK_int.

If anInteger is MAXINT, this method is the same as [self removePar: parameterTag].

Parameters:

	parameterTag	is an int.
	anInteger	is an int.

Returns:: Returns self.

See also:: ++ parTagForName:, ++ parNameForTag:, -- parType:, -- isParPresent:, -parAsInteger:

- (id) setPar:	(int)	parameterTag
toString:	(NSString *)	aString

Sets the value of the parameter identified by parameterTag to aString, and sets its data type to MK_string.

If aStringis NULL or "", this method is the same as [self removePar:parameterTag].

Parameters:

	parameterTag	is an int.
	aString	is an NSString instance.

Returns:: Returns self.

See also:: ++ parTagForName:, ++ parNameForTag:, -- parType:, -- isParPresent:, -- parAsString:

- (id) setPar:	(int)	parameterTag
toEnvelope:	(id)	anEnvelope

Sets the value of the parameter identified by parameterTag to anEnvelope, and sets its data type to MK_envelope.

If anEnvelopeis nil , this method is the same as [self removePar: parameterTag].

Parameters:

	parameterTag	is an int.
	anEnvelope	is an id. TODO Should be an MKEnvelope.

Returns:: Returns self.

See also:: ++ parTagForName:, ++ parNameForTag:, -- parType:, -- isParPresent:, -- parAsEnvelope:

- (id) setPar:	(int)	parameterTag
toWaveTable:	(id)	aWaveTable

Sets the value of the parameter identified by parameterTag to aWaveTable, and sets its data type to MK_waveTable.

If aWaveTableis nil , this method is the same as [self removePar: parameterTag].

Parameters:

	parameterTag	is an int.
	aWaveTable	is an MKWaveTable object.

Returns:: Returns self.

See also:: ++ parTagForName:, ++ parNameForTag:, -- parType:, -- isParPresent:, -- parAsWaveTable:

- (id) setPar:	(int)	parameterTag
toObject:	(id)	anObject

Sets the value of the parameter identified by parameterTag to anObject, and sets its data type to MK_object.

If anObjectis nil, this method is the same as [self removePar: parameterTag].

While you can use this method to set the value of a parameter to any object, it's designed, principally, to allow you to use an instance of one of your own classes as a parameter value. If you want the object to be written to and read from a scorefile, it must respond to the messages writeASCIIStream: and readASCIIStream:. While response to these messages isn't a prerequisite for an object to be used as the argument to this method, if you try to write a MKNote that contains a parameter that doesn't respond to writeASCIIStream:, an error is generated. An object's ASCII representation shouldn't contain the character ']'.

Note that unless you really need to write your object to a Scorefile, you are better off saving your object using the NXTypedStream archiving mechanism.

None of the MusicKit classes implement readASCIIStream: or writeASCIIStream: so you can't use this method to set a parameter to a MusicKit object. If you're setting the value as an MKEnvelope or MKWaveTable object, you should use the setPar:toEnvelope: or setPar:toWaveTable: method, respectively.

Parameters:

	parameterTag	is an int.
	anObject	is an id.

Returns:: Returns self.

See also:: ++ parTagForName:, ++ parNameForTag:, -- parType:, -- isParPresent:, -- parAsObject:

- (double) parAsDouble: (int) parameterTag

Returns a double value converted from the value of the parameter identified by parameterTag.

If the parameter isn't present or if its value is an object, returns MK_NODVAL (use the function MKIsNoDVal() to check for MK_NODVAL). You should use the freq method if you're want to retrieve the frequency of the MKNote.

Parameters:

parameterTag

is an int.

Returns:: Returns a double.

See also:: MKGetNoteParAsDouble(), -- setPar:toDouble: (etc), -- parType:, -- isParPresent:

- (int) parAsInt: (int) parameterTag

Returns an int value converted from the value of the parameter identified by parameterTag.

If the parameter isn't present, or if its value is an object, returns MAXINT.

Parameters:

parameterTag

is an int.

Returns:: Returns an int.

See also:: MKGetNoteParAsInt(), -- setPar:toDouble: (etc), -- parType:, - isParPresent:

- (NSString *) parAsString: (int) parameterTag

Returns a string converted from a copy of the value of the parameter identified by parameterTag.

If the parameter isn't present, or if its value is an object, returns an empty string.

Parameters:

parameterTag

is an int.

Returns:: Returns an NSString.

See also:: MKGetNoteParAsString(), -- setPar:toDouble: (etc), -- parType:, - isParPresent:

- (NSString *) parAsStringNoCopy: (int) parameterTag

Returns a string converted from a the value of the parameter identified by parameterTag.

If the parameter was set as a string, then this returns a pointer to the actual string itself; you should neither delete nor alter the value returned by this method. If the parameter isn't present, or if its value is an object, returns an empty string.

Parameters:

parameterTag

is an int.

Returns:: Returns an NSString.

See also:: MKGetNoteParAsStringNoCopy(), -- setPar:toDouble: (etc), -- parType:, -- isParPresent:

- (id) parAsEnvelope: (int) parameterTag

Returns the MKEnvelope value of parameterTag.

If the parameter isn't present or if its value isn't an MKEnvelope, returns nil.

Parameters:

parameterTag

is an int.

Returns:: Returns an id.

See also:: MKGetNoteParAsEnvelope(), -- setPar:toDouble: (etc), -- parType:, -- isParPresent:

- (id) parAsWaveTable: (int) parameterTag

Returns the MKWaveTable value of the parameter identified by parameterTag.

If the parameter isn't present, or if it's value isn't a MKWaveTable, returns nil.

Parameters:

parameterTag

is an int.

Returns:: Returns an id.

- (id) parAsObject: (int) parameterTag

Returns the object value of the parameter identified by parameterTag.

If the parameter isn't present, or if its value isn't an object, returns nil. This method can be used to return MKEnvelope and MKWaveTable objects, in addition to non-MusicKit objects.

Parameters:

parameterTag

is an int.

Returns:: Returns an id.

See also:: MKGetNoteParAsObject(), -- setPar:toDouble: (etc), -- parType:, -- isParPresent:

- (BOOL) isParPresent: (int) parameterTag

Returns YES if the parameter identified by parameterTag is present in the MKNote (in other words, if its value has been set), and NO if it isn't.

See also:: -- parVector:, MKIsNoteParPresent(), MKNextParameter(), ++ parTagForName:, ++ parNameForTag:, -- parType:, -- setPar:toDouble: (etc), -- parAsDouble: (etc).

Parameters:

parameterTag

is an int.

Returns:: Returns a BOOL.

- (MKDataType) parType: (int) parameterTag

Returns the data type of the value of the parameter identified by parameterTag.

The data type is set when the parameter's value is set; the specific data type of the value, one of the MKDataType constants listed below, depends on which method you used to set it:

Method Data type

setPar:toInt: MK_int

setPar:toDouble: MK_double

setPar:toString: MK_string

setPar:toWaveTable: MK_waveTable

setPar:toEnvelope: MK_envelope

setPar:toObject: MK_object

If the parameter's value hasn't been set, MK_noType is returned.

Parameters:

parameterTag

is an int.

Returns:: Returns a MKDataType.

See also:: MKGetNoteParAsWaveTable(), -- setPar:toDouble: (etc), -- parType:, -- isParPresent:

- (id) removePar: (int) parameterTag

Removes the parameter identified by parameterTag from the MKNote; in other words, this sets the parameter's value to indicate that the parameter isn't set.

If the parameter was present, then the MKNote is returned; if not, nil is returned.

Parameters:

parameterTag

is an int.

Returns:: Returns an id.

See also:: ++ parTagForName:, ++ parNameForTag:, -- isParPresent:, -- setPar:toDouble: (etc).

- (id) copyParsFrom: (MKNote *) aNote

Copies aNote's parameters into the receiving MKNote.

Object-valued parameters are shared by the two MKNotes.

Parameters:

aNote

is an MKNote instance.

Returns:: Returns self.

See also:: -copy, -copyFromZone:, -split::

- (double) freq

This method returns the MKNote's frequency, measured in Hertz or cycles-per-second.

If the frequency parameter MK_freq is present, its value is returned; otherwise, the frequency is converted from the key number value given by the MK_keyNum parameter according to the installed tuning system (see the MKTuningSystem class). In the absence of both MK_freq and MK_keyNum, MK_NODVAL is returned (use the function MKIsNoDVal() to check for MK_NODVAL). The correspondence between key numbers and frequencies is given in the section entitled Music Tables .

Frequency and key number are the only two parameters whose values are retrieved through specialized methods. All other parameter values should be retrieved through one of the parAsType: methods.

Returns:: Returns a double.

See also:: -- keyNum, -- setPar:toDouble:

- (int) keyNum

This method returns the key number of the MKNote.

Key numbers are integers that enumerate discrete pitches; they're provided primarily to accommodate MIDI. If the MK_keyNum parameter is present, its value is returned; otherwise, the key number that corresponds to the value of the MK_freq parameter, if present, is returned. This value is computed according to the installed tuning system (see the MKTuningSystem class). In the absence of both MK_keyNum and MK_freq, MAXINT is returned. The correspondence between key numbers and frequencies is given in the section entitled Music Tables .

Frequency and key number are the only two parameters whose values are retrieved through specialized methods. All other parameter values should be retrieved through one of the parAsType: methods.

Returns:: Returns an int.

See also:: -- freq, -- setPar:toInt:

- (id) writeScorefileStream: (NSMutableData *) aStream

Writes the MKNote, in scorefile format, to the stream, that is, the data object aStream.

You rarely invoke this method yourself; it's invoked from the scorefile-writing methods defined by MKScore and MKScorefileWriter.

Parameters:

aStream

is a NSMutableData instance.

Returns:: Returns self.

- (int) parVectorCount

Returns the number of parameter bit vectors that the MKNote is using to accommodate all its parameters identifiers.

Normally you only need to know this if you're iterating over the parameter vectors.

Returns:: Returns an int.

See also:: -parVector

- (unsigned) parVector: (unsigned) index

Returns an integer bit vector that indicates the presence of the index'th set of parameters.

Each bit vector represents 32 parameters. For example, if index is 1, the bits in the returned value indicate the presence of parameters 0 through 31, where 1 means the parameter is present and 0 means that it's absent. An index of 2 returns a vector that represents parameters 32 through 63, and so on. To query for the presence of a particular parameter, use the following predicate formula:

[aNote parVector: (parameterTag / 32)] & (1 << (parameterTag % 32))

In this formula, parameterTag identifies the parameter that you're interested in. Keep in mind that the parameter bit vectors only indicate the presence of a parameter, not its value.

Parameters:

index

is an unsigned.

Returns:: Returns an unsigned.

See also:: -- parVectorCount, -- isParPresent:

+ (id) note

Allocates and initializes a new MKNote and returns it autoreleased.

Returns:: Returns a MKNote.

+ (id) noteWithTimeTag: (double) aTimeTag

Allocates and initializes a new MKNote and returns it autoreleased.

Sets timeTag as specified and sets type to mute. If aTimeTag is MK_ENDOFTIME, the timeTag isn't set.

Parameters:

aTimeTag

is a double in seconds.

Returns:: Returns a MKNote.

Member Data Documentation

- (MKNoteType) noteType [protected]

The MKNote's noteType.

- (int) noteTag [protected]

The MKNote's noteTag.

- (MKPerformer*) performer [protected]

MKPerformer object that's currently sending the MKNote in performance, if any.

- (MKPart*) part [protected]

The MKPart that this MKNote is a member of, if any.

- (double) timeTag [protected]

Time tag, if any, else MK_ENDOFTIME.

- (MKConductor*) conductor [protected]

MKConductor to use if performer is nil. If performer is not nil, uses [performer conductor].

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

MKNote.h


Public Member Functions
(id)	- initWithTimeTag:
	Sets timeTag as specified and sets type to mute.
(id)	- init
	Initializes a MKNote that was created through allocFromZone:.
(void)	- dealloc
	Removes the receiver from its MKPart, if any, and then frees the receiver and its contents.
(id)	- copyWithZone:
	Creates and returns a new MKNote object as a copy of the receiver.
(id)	- split::
	This method splits a noteDur into a noteOn/noteOff pair, as described below.
(MKPerformer *)	- performer
	Returns the MKPerformer that most recently performed the MKNote.
(MKPart *)	- part
	Returns the MKPart that contains the MKNote, or nil if none.
(MKConductor *)	- conductor
	If the MKNote is being sent by a MKPerformer (or MKMidi), returns the MKPerformer's MKConductor.
(void)	- setConductor:
	Sets conductor instance variable.
(MKPart *)	- addToPart:
	Removes the MKNote from the MKPart that it's currently a member of and adds it to aPart.
(double)	- timeTag
	Returns the MKNote's time tag.
(double)	- setTimeTag:
	Sets the MKNote's time tag to newTimeTag or 0.0, whichever is greater (a time tag can't be negative).
(double)	- setTimeTagPreserveEndTime:
	Sets the receiver's timeTag to newTimeTag and returns the old timeTag, or MK_ENDOFTIME if none.
(MKPart *)	- removeFromPart
	Removes the MKNote from its MKPart.
(int)	- compare:
	Returns a value that indicates which of the receiving MKNote and the argument MKNote would appear first if the two MKNotes were sorted into the same MKPart.
(MKNoteType)	- noteType
	Returns the MKNote's note type, one of MK_noteDur, MK_noteOn, MK_noteOff, MK_noteUpdate, or MK_mute.
(id)	- setNoteType:
	Sets the MKNote's note type to newNoteType.
(double)	- setDur:
	Sets the MKNote's duration to value beats and sets its note type to MK_noteDur.
(double)	- dur
	If the MKNote has a duration, returns the duration, or MK_NODVAL if it isn't set (use the function MKIsNoDVal() to check for MK_NODVAL).
(double)	- setEndTime:
	Returns the receiver's old end time (duration + timeTag) and sets duration to newEndTime - timeTag, or MK_NODVAL if not a MK_noteDur or MK_mute.
(double)	- endTime
	Returns the receiver's end time (duration + timeTag), or MK_NODVAL if not a MK_noteDur or MK_mute.
(int)	- noteTag
	Return the MKNote's note tag, or MAXINT if it isn't set.
(id)	- setNoteTag:
	Sets the MKNote's note tag to newTag; if the note type is MK_mute it's changed to MK_noteUpdate.
(id)	- removeNoteTag
	Removes the noteTag, if any.
(id)	- setPar:toDouble:
	Sets the value of the parameter identified by parameterTag to aDouble, and sets its data type to MK_double.
(id)	- setPar:toInt:
	Sets the value of the parameter identified by parameterTag to anInteger, and sets its data type to MK_int.
(id)	- setPar:toString:
	Sets the value of the parameter identified by parameterTag to aString, and sets its data type to MK_string.
(id)	- setPar:toEnvelope:
	Sets the value of the parameter identified by parameterTag to anEnvelope, and sets its data type to MK_envelope.
(id)	- setPar:toWaveTable:
	Sets the value of the parameter identified by parameterTag to aWaveTable, and sets its data type to MK_waveTable.
(id)	- setPar:toObject:
	Sets the value of the parameter identified by parameterTag to anObject, and sets its data type to MK_object.
(double)	- parAsDouble:
	Returns a double value converted from the value of the parameter identified by parameterTag.
(int)	- parAsInt:
	Returns an int value converted from the value of the parameter identified by parameterTag.
(NSString *)	- parAsString:
	Returns a string converted from a copy of the value of the parameter identified by parameterTag.
(NSString *)	- parAsStringNoCopy:
	Returns a string converted from a the value of the parameter identified by parameterTag.
(id)	- parAsEnvelope:
	Returns the MKEnvelope value of parameterTag.
(id)	- parAsWaveTable:
	Returns the MKWaveTable value of the parameter identified by parameterTag.
(id)	- parAsObject:
	Returns the object value of the parameter identified by parameterTag.
(BOOL)	- isParPresent:
	Returns YES if the parameter identified by parameterTag is present in the MKNote (in other words, if its value has been set), and NO if it isn't.
(MKDataType)	- parType:
	Returns the data type of the value of the parameter identified by parameterTag.
(id)	- removePar:
	Removes the parameter identified by parameterTag from the MKNote; in other words, this sets the parameter's value to indicate that the parameter isn't set.
(id)	- copyParsFrom:
	Copies aNote's parameters into the receiving MKNote.
(double)	- freq
	This method returns the MKNote's frequency, measured in Hertz or cycles-per-second.
(int)	- keyNum
	This method returns the key number of the MKNote.
(id)	- writeScorefileStream:
	Writes the MKNote, in scorefile format, to the stream, that is, the data object *aStream*.
(int)	- parVectorCount
	Returns the number of parameter bit vectors that the MKNote is using to accommodate all its parameters identifiers.
(unsigned)	- parVector:
	Returns an integer bit vector that indicates the presence of the index'th set of parameters.
Static Public Member Functions
(int)	+ parTagForName:
	Returns the integer that identifies the parameter named aName.
(NSString *)	+ parNameForTag:
	Returns the name that identifies the parameter tagged aTag.
(id)	+ note
	Allocates and initializes a new MKNote and returns it autoreleased.
(id)	+ noteWithTimeTag:
	Allocates and initializes a new MKNote and returns it autoreleased.
Protected Attributes
MKNoteType	noteType
int	noteTag
MKPerformer *	performer
MKPart *	part
double	timeTag
MKConductor *	conductor

Retrieval type	No-set value
int	MAXINT
double	MK_NODVAL (but see below)
NSString	@“”
id	nil

Method	Data type
setPar:toInt:	MK_int
setPar:toDouble:	MK_double
setPar:toString:	MK_string
setPar:toWaveTable:	MK_waveTable
setPar:toEnvelope:	MK_envelope
setPar:toObject:	MK_object