MKPart Class Reference

A MKPart is a timeTag-ordered collection of MKNotes that can be edited performed, and realized. MKParts are typically grouped together in an MKScore. More...

#import <MKPart.h>

List of all members.

Public Member Functions
(id)	- sort
	Causes the MKPart to sort itself if it's currently unsorted.
(BOOL)	- isSorted
	Returns YES if the MKPart's MKNotes are currently guaranteed to be in time tag order, otherwise returns NO.
(id)	- combineNotes
	Creates and adds a single noteDur for each noteOn/noteOff pair in the MKPart.
(id)	- splitNotes
	Splits the MKPart's noteDurs into noteOn/noteOff pairs.
(id)	- addToScore:
	Moves the MKPart from its present MKScore, if any, to aScore.
(id)	- removeFromScore
	Removes the MKPart from its present MKScore.
(id)	- init
	Initializes the object. This should be invoked when alloc'ing a new MKPart.
(void)	- dealloc
	Deallocates ivars.
(id)	- releaseNotes
	Removes and frees the MKPart's MKNotes and its info MKNote.
(id)	- releaseSelfOnly
	THIS IS DEPRECATED. DO NOT USE. EXPECT IT TO BE REMOVED SOON.
(id)	- firstTimeTag:lastTimeTag:
	Creates and returns a NSMutableArray of the MKPart's MKNotes that have time tag values between firstTimeTag and lastTimeTag, inclusive.
(MKPart *)	- addNote:
	Moves aNote from its present MKPart to the receiving MKPart.
(MKNote *)	- addNoteCopy:
	Adds a copy of aNote to the MKPart.
(MKNote *)	- removeNote:
	Removes aNote from the MKPart.
(id)	- removeNotes:
	Removes all the MKNotes the MKPart has in common with aNoteList.
(void)	- removeAllNotes
	Deletes all MKNotes within this part.
(id)	- addNoteCopies:timeShift:
	Copies each MKNote in aNoteList (which should be a NSMutableArray object) adds shift to each new MKNote's time tag, then adds the new MKNotes to the MKPart by repeatedly invoking addNote:.
(id)	- addNotes:timeShift:
	Moves each MKNote in aNoteList from its present MKPart to the receiving MKPart, adding shift to each MKNote's time tag in the process.
(id)	- shiftTime:
	Shifts the MKPart's contents by adding shift to each of the MKNotes' time tags.
(id)	- scaleTime:
	Scales the MKPart's contents by multiplying scale to each of the MKNotes' time tags and durations.
(unsigned)	- noteCount
	Returns the number of MKNotes in the MKPart (not counting the info MKNote).
(BOOL)	- containsNote:
	Returns YES if the MKPart contains aNote, otherwise returns NO.
(BOOL)	- hasSoundingNotes
	Returns YES if the MKPart contains any MK_noteDur or MK_noteOn notes.
(BOOL)	- isEmpty
	Returns YES if the MKPart contains no MKNotes (not including the info MKNote), otherwise returns NO.
(MKNote *)	- atTime:
	Returns the (first) MKNote in the MKPart that has a time tag of timeTag, or nil if none.
(MKNote *)	- atOrAfterTime:
	Returns the first MKNote with a time tag equal to or greater than timeTag, or nil if none.
(MKNote *)	- atOrBeforeTime:
	Returns the first MKNote with a time tag equal to or less than timeTag, or nil if none.
(MKNote *)	- nth:
	Returns the nth MKNote (0-based), or nil if n is out of bounds (negative or greater than the MKPart's MKNote count).
(MKNote *)	- atOrAfterTime:nth:
	Returns the nth MKNote (zero-based) in the MKPart that has a time tag equal to or greater than timeTag, or nil if none.
(MKNote *)	- atTime:nth:
	Returns the nth MKNote (zero-based) in the MKPart that has a time tag of timeTag, or nil if none.
(MKNote *)	- next:
	Returns the MKNote immediately following aNote, or nil if aNote isn't a member of the MKPart, or if it's the last MKNote in the MKPart.
(double)	- earliestNoteTime
	Returns the time of the earliest note in the part.
(id)	- copyWithZone:
	This is the same as copy, but the new MKNote is allocated in aZone.
(id)	- copy
	Creates and returns a new MKPart as a copy of the receiving MKPart.
(NSArray *)	- notes
	Creates and returns a NSArray of the MKPart's MKNotes in time order.
(NSMutableArray *)	- notesNoCopy
	Returns the NSMutableArray object that contains the MKPart's MKNotes.
(MKScore *)	- score
	Returns the MKScore the MKPart is a member of, or nil if none.
(MKNote *)	- infoNote
	Returns the MKPart's info MKNote.
(void)	- setInfoNote:
	Sets the MKPart's info MKNote to a copy of aNote.
(NSString *)	- partName
	Return the name of the receiver.
(void)	- setPartName:
	Assigns the name of the receiver.
Static Public Member Functions
(MKPart *)	+ part
	Returns a newly allocated, initialized and autoreleased MKPart.
(id)	+ partWithName:
	Returns a newly allocated, initialized and autoreleased MKPart with the given name.
Protected Attributes
MKScore *	score
NSMutableArray *	notes
MKNote *	info
unsigned int	noteCount
BOOL	isSorted

---

Detailed Description

A MKPart is a timeTag-ordered collection of MKNotes that can be edited performed, and realized. MKParts are typically grouped together in an MKScore.

A MKPart is a timeTag-ordered collection of MKNotes that can be edited performed, and realized. MKParts are typically grouped together in a MKScore.

A MKNote can belong to only one MKPart at a time, and a MKPart to only one MKScore. When you add a MKNote to a MKPart, it's automatically removed from its old MKPart. Similarly, adding a MKPart to a MKScore removes it from its previous MKScore.

You can add MKNotes to a MKPart either by invoking one of MKPart's addNote: methods, or by “recording” them with a MKPartRecorder, a type of MKInstrument that realizes MKNotes by adding copies of them to a specified MKPart. Any number of MKPartRecorders can simultaneously record into the same MKPart. A MKPart is added to a MKScore through MKPart's addToScore: method (or the equivalent MKScore method addPart:).

Within a MKPart, MKNotes are ordered by their time tag values, lowest to highest. To move a MKNote within a MKPart, you simply change the MKNote's time tag (through MKNote's setTimeTag: method). For efficiency, a MKPart sorts itself only when its MKNotes are retrieved or when a MKNote is moved within the MKPart (or removed altogether). In other words, adding a MKNote to a MKPart won't cause the MKPart to sort itself; but keep in mind that since adding a MKNote to a MKPart automatically removes it from its current MKPart, the act will cause the moved-from MKPart to sort itself. You can force a MKPart to sort itself by sending it a sortmessage.

A MKPart can be a source of MKNotes in a performance through association with a MKPartPerformer. During a performance, the MKPartPerformer reads the MKNotes in the MKPart, performing them in order. While you shouldn't free a MKPart or any of its MKNotes while an associated MKPartPerformer is active, you can add MKNotes to and remove MKNotes from the MKPart at any time without affecting the MKPartPerformer's performance.

A MKPart can be performed using a MKPartPerformer and can 'record' notes by using a MKPartRecorder. You must not free a MKPart or any of the MKNotes in a MKPart while there are any MKPartPerformers using the MKPart. It is ok to record to a part and perform that part at the same time because the MKPartPerformer takes a snap-shot of the MKPart when the MKPartPerformer is activated.

A MKPartPerformer creates its own NSMutableArray of the MKPart's MKNotes when it receives the setPart: message (but keep in mind that it doesn't make copies of the MKNotes themselves); changes to the MKPart made during a performance won't affect the MKPartPerformer. This allows a MKPart to be performed by a MKPartPerformer and used for recording by a MKPartRecorder at the same time.

To each MKPart you can give an info MKNote, a sort of header for the MKPart that can contain any amount and type of information. Info MKNotes are typically used to describe a performance setup; for example, an info MKNote might contain, as a parameter, the name of the MKSynthPatch subclass on which the MKNotes in the MKPart are meant to be synthesized. When the MKPart's MKScore is written to a scorefile, the info MKNote is written in the file's header; this is in distinction to the MKPart's other MKNotes, which make up the body of the scorefile. (To store a MKPart in a scorefile you must first add it to a MKScore and then write the MKScore.)

Keep in mind that a MKPart's info MKNote must be interpreted by your application if it is to have any effect. A few parameters defined by the MusicKit are designed specifically to be used in a MKPart's info MKNote. These are listed in the description of the setInfo: method, below. The info MKNote is stored separately from the MKNotes in the body of the MKPart; most of the MKNote-accessing methods, such as empty, nth:, and next:, don't apply to the info MKNote. The exceptions - the methods that do affect the info MKNote - are so noted in their descriptions below.

MKParts are commonly given string name identifiers, through the MKNameObject() C function. The most important use of a MKPart's name is to identify the MKPart in a scorefile.

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

Editing a MKPart refers generally to adding and removing MKNotes, not to changing the contents of the MKNotes themselves (although some methods do both; see splitNotes and combineNotes). MKNotes are ordered within the MKPart by their timeTag values. To move a MKNote within a MKPart, you simply change its timeTag by sending it the appropriate message (see the MKNote class). This effectively removes the MKNote from its MKPart, changes the timeTag, and then adds it back to its MKPart.

The MKNotes in a MKPart are stored in a NSArray object. The NSArray is only sorted when necessary. In particular, the NSArray is sorted, if necessary, when an access method is invoked. The access methods are:

• firstTimeTag: (double) firstTimeTag lastTimeTag: (double) lastTimeTag;
• atTime: (double) timeTag;
• atOrAfterTime: (double) timeTag;
• nth: (unsigned) n;
• atOrAfterTime: (double) timeTag nth: (unsigned) n;
• atTime: (double) timeTag nth: (unsigned) n;
• next: (MKNote *) aNote;
• notes;

Other methods that cause a sort, if necessary, are:

• combineNotes;
• removeNotes: (NSArray *) aList;
• removeNote: (MKNote *) aNote;

Methods that may alter the NSArray such that its MKNotes are no longer sorted are the following:

• addNoteCopies: (NSArray *) aList timeShift: (double) shift;
• addNotes: (NSArray *) aList timeShift: (double) shift;
• addNote: (MKNote *) aNote;
• addNoteCopy: (MKNote *) aNote;
• splitNotes;

This scheme works well for most cases. However, there are situations where it can be problematic. For example:

for (i = 0; i < 100; i++) {
  [aPart addNote: anArray[i]];
  [aPart removeNote: anotherArray[i]];
}

In this case, the MKPart will be sorted each time removeNote: is called, causing N-squared behavior. You can get around this by first adding all the notes using addNotes: and then removing all the notes using removeNotes:.

In some cases, you may find it most convenient to remove the MKNotes from the MKPart, modify them in your own data structure, and then reinsert them into the MKPart.

You can explicitly trigger a sort (if needed) by sending the -sort message. This is useful if you ever subclass MKPart.

To get a sorted copy of the NSArray of notes use the -notes method. To get the NSArray of notes itself, use the -notesNoCopy method. -notesNoCopy does not guarantee the MKNotes are sorted. If you want to examine the MKNotes in-place sorted, first send -sort, then -notesNoCopy.

You can find out if the NSArray is currently sorted by the -isSorted method.

---

Member Function Documentation

+ (MKPart *) part

Returns a newly allocated, initialized and autoreleased MKPart.

Returns:

Returns an MKPart instance.

+ (id) partWithName:

(NSString *)

partName

Returns a newly allocated, initialized and autoreleased MKPart with the given name.

Parameters:

partName

is an NSString instance.

Returns:

Returns a newly allocated, initialized and autoreleased MKPart.

- (id) sort

Causes the MKPart to sort itself if it's currently unsorted.

Returns:

Returns self. Normally, a MKPart sorts itself only when MKNotes are accessed, moved, or removed.

See also:

-isSorted

- (BOOL) isSorted

Returns YES if the MKPart's MKNotes are currently guaranteed to be in time tag order, otherwise returns NO.

Returns:

Returns a BOOL.

See also:

-- sort

- (id) combineNotes

Creates and adds a single noteDur for each noteOn/noteOff pair in the MKPart.

Returns:

Returns self. A noteOn/noteOff pair is identified by pairing a noteOn with the earliest subsequent noteOff that has a matching note tag. The parameters from the two MKNotes are merged in the noteDur. If the noteOn and its noteOff have different values for the same parameter, the value from the noteOn takes precedence. The noteDur's duration is the time tag difference between the two original MKNotes. After the noteDur is created and added to the MKPart, the noteOn and noteOff are removed and freed.

See also:

-- splitNotes

- (id) splitNotes

Splits the MKPart's noteDurs into noteOn/noteOff pairs.

Returns:

Returns an id. Each noteDur's note type is set to noteOn and a noteOff is created (and added) to complement it. The original parameters and note tag are divided between the two MKNotes as described in MKNote's split:: method. Returns self.

See also:

-- combineNotes:, -split:: (MKNote)

- (id) addToScore:

(MKScore *)

newScore

Moves the MKPart from its present MKScore, if any, to aScore.

Parameters:

newScore

is an MKScore instance.

Returns:

Returns self. Implemented in terms of MKScore's addPart: method.

See also:

-- removeFromScore:, -score

- (id) removeFromScore

Removes the MKPart from its present MKScore.

Returns:

Returns self, or nil if it isn't part of a MKScore. This is implemented in terms of MKScore's removePart: method.

See also:

-- addToScore:, -score

- (id) init

Initializes the object. This should be invoked when alloc'ing a new MKPart.

Returns:

Returns an id.

- (id) releaseNotes

Removes and frees the MKPart's MKNotes and its info MKNote.

Returns:

Returns an id. Removes the receiver's name from the name table. If the MKPart has an active MKPartPerformer associated with it, this does nothing. Returns nil.

See also:

-empty, -- removeNotes:

- (id) releaseSelfOnly

THIS IS DEPRECATED. DO NOT USE. EXPECT IT TO BE REMOVED SOON.

Returns:

Returns an id. Frees the MKPart but not its MKNotes. The MKPart is removed from its MKScore, if any. You can free a MKPart while its being performed by a MKPartPerformer - it's the MKPart's MKNotes, not the MKPart itself, that's performed.

See also:

-empty, -- removeNotes:

- (id) firstTimeTag:		(double)	firstTimeTag
lastTimeTag:		(double)	lastTimeTag

Creates and returns a NSMutableArray of the MKPart's MKNotes that have time tag values between firstTimeTag and lastTimeTag, inclusive.

Parameters:

	firstTimeTag	is a double.
	lastTimeTag	is a double.

Returns:

Returns an id. The MKNotes themselves are not copied. The sender is responsible for freeing the NSMutableArray. The object returned by this method is useful as the NSMutableArray argument in methods such as addNotes: (sent to another MKPart), addNotes:timeShift:, and removeNotes:.

- (MKPart *) addNote:

(MKNote *)

aNote

Moves aNote from its present MKPart to the receiving MKPart.

Parameters:

aNote

is an MKNote.

Returns:

Returns aNote's old MKPart, or nil if none.

See also:

-- addNoteCopy:, -- addNotes:timeShift:, -- removeNote:

- (MKNote *) addNoteCopy:

(MKNote *)

aNote

Adds a copy of aNote to the MKPart.

Parameters:

aNote

is an MKNote.

Returns:

Returns the new MKNote. Implemented in terms of addNote:.

See also:

-- addNote:, -- addNoteCopies:timeShift:, -- removeNote:

- (MKNote *) removeNote:

(MKNote *)

aNote

Removes aNote from the MKPart.

Parameters:

aNote

is an MKNote.

Returns:

Returns the MKNote or nil if it isn't found. You shouldn't invoke this method if the MKPart has an active MKPartPerformer associated with it.

See also:

-- removeNotes:, -empty, -addNote

- (id) removeNotes:

(NSArray *)

aNoteList

Removes all the MKNotes the MKPart has in common with aNoteList.

Parameters:

aNoteList

is an NSArray instance.

Returns:

Returns self.

See also:

-- removeNote:, -empty, -- addNote:, -- firstTimeTag:lastTimeTag:

- (id) addNoteCopies:		(NSArray *)	aNoteList
timeShift:		(double)	shift

Copies each MKNote in aNoteList (which should be a NSMutableArray object) adds shift to each new MKNote's time tag, then adds the new MKNotes to the MKPart by repeatedly invoking addNote:.

Parameters:

	aNoteList	is an NSArray instance.
	shift	is a double.

Returns:

Returns self, or nil if aNoteList is nil. The MKNotes in aNoteList are unaffected. aNoteList is typically generated through MKPart's notes or firstTimeTag:lastTimeTag: method. In this way, all or a portion of one MKPart can be copied into another.

See also:

-- addNotes:timeShift:, -shift

- (id) addNotes:		(NSArray *)	aNoteList
timeShift:		(double)	shift

Moves each MKNote in aNoteList from its present MKPart to the receiving MKPart, adding shift to each MKNote's time tag in the process.

Parameters:

	aNoteList	is an NSArray instance.
	shift	is a double.

Returns:

Returns self, or nil if aNoteList is nil. Implemented in terms of addNote:. The NSMutableArray argument is typically generated through MKPart's notes or firstTimeTag:lastTimeTag: method. In this way, all or a portion of one MKPart can be merged into another.

See also:

-- addNoteCopies:timeShift:, -shift:

- (id) shiftTime:

(double)

shift

Shifts the MKPart's contents by adding shift to each of the MKNotes' time tags.

Parameters:

shift

is a double.

Returns:

Returns self. Implemented in terms of addNotes:timeShift:. Notice that this means the MKNotes are removed and then readded to the MKPart. Returns the MKPart.

- (id) scaleTime:

(double)

scale

Scales the MKPart's contents by multiplying scale to each of the MKNotes' time tags and durations.

Parameters:

scale

is a double.

Returns:

Returns self.

- (unsigned) noteCount

Returns the number of MKNotes in the MKPart (not counting the info MKNote).

Returns:

Returns an unsigned.

See also:

-notes, -- isEmpty

- (BOOL) containsNote:

(MKNote *)

aNote

Returns YES if the MKPart contains aNote, otherwise returns NO.

Parameters:

aNote

is an id.

Returns:

Returns a BOOL.

See also:

-- isEmpty, -noteCount

- (BOOL) hasSoundingNotes

Returns YES if the MKPart contains any MK_noteDur or MK_noteOn notes.

Returns:

Returns a BOOL.

- (BOOL) isEmpty

Returns YES if the MKPart contains no MKNotes (not including the info MKNote), otherwise returns NO.

Returns:

Returns a BOOL.

See also:

-noteCount

- (MKNote *) atTime:

(double)

timeTag

Returns the (first) MKNote in the MKPart that has a time tag of timeTag, or nil if none.

Parameters:

timeTag

is a double.

Returns:

Returns an MKNote instance. Invokes MKNote's compareNotes: method if the MKPart contains more than one such MKNote.

See also:

-- atOrAfterTime:, -- atTime:nth:, -next

- (MKNote *) atOrAfterTime:

(double)

timeTag

Returns the first MKNote with a time tag equal to or greater than timeTag, or nil if none.

Parameters:

timeTag

is a double.

Returns:

Returns an MKNote instance.

See also:

-- atTime:, -- atOrAfterTime:nth:, -next

- (MKNote *) atOrBeforeTime:

(double)

timeTag

Returns the first MKNote with a time tag equal to or less than timeTag, or nil if none.

Parameters:

timeTag

is a double.

Returns:

Returns an MKNote instance.

- (MKNote *) nth:

(unsigned)

n

Returns the nth MKNote (0-based), or nil if n is out of bounds (negative or greater than the MKPart's MKNote count).

Parameters:

n

is an unsigned.

Returns:

Returns an MKNote instance.

See also:

-notes, -noteCount, -- atTime:

- (MKNote *) atOrAfterTime:		(double)	timeTag
nth:		(unsigned)	n

Returns the nth MKNote (zero-based) in the MKPart that has a time tag equal to or greater than timeTag, or nil if none.

Parameters:

	timeTag	is a double.
	n	is an unsigned.

Returns:

Returns an MKNote instance.

See also:

-- atTime:, -- atOrAfterTime:, -next

- (MKNote *) atTime:		(double)	timeTag
nth:		(unsigned)	n

Returns the nth MKNote (zero-based) in the MKPart that has a time tag of timeTag, or nil if none.

Parameters:

	timeTag	is a double.
	n	is an unsigned.

Returns:

Returns an MKNote instance.

See also:

-- atTime:, -- atOrAfterTime:, -next

- (MKNote *) next:

(MKNote *)

aNote

Returns the MKNote immediately following aNote, or nil if aNote isn't a member of the MKPart, or if it's the last MKNote in the MKPart.

Parameters:

aNote

is an MKNote instance.

Returns:

Returns an MKNote instance. For greater efficiency, you should create a NSMutableArray from the notes method and then iterate over the array.

See also:

-- nth:, -- atTime:, -- atOrAfterTime:

- (double) earliestNoteTime

Returns the time of the earliest note in the part.

Returns 0.0 if there are no notes in the part.

Returns:

Returns a double being the time tag of the first note.

- (id) copyWithZone:

(NSZone *)

zone

This is the same as copy, but the new MKNote is allocated in aZone.

Parameters:

zone

is a NSZone instance.

Returns:

Returns an id.

See also:

-- copy

- (id) copy

Creates and returns a new MKPart as a copy of the receiving MKPart.

Returns:

Returns an id. The new MKPart contains copies of receiving MKPart's MKNotes (including the info MKNote). The new MKPart is added to the same MKScore as the receiving MKPart, but is left unnamed.

See also:

-copyFromZone:

- (NSArray *) notes

Creates and returns a NSArray of the MKPart's MKNotes in time order.

Returns:

Returns an NSArray. The MKPart is sorted before the NSArray is created. The MKNotes themselves are copied (for the moment, but ideally not). The NSArray is autoreleased and should be retained if required.

See also:

-- notesNoCopy, -noteCount

- (NSMutableArray *) notesNoCopy

Returns the NSMutableArray object that contains the MKPart's MKNotes.

Returns:

Returns an id. The NSMutableArray isn't guaranteed to be sorted. The MKNotes are not copied.

See also:

-notes, -noteCount

- (MKScore *) score

Returns the MKScore the MKPart is a member of, or nil if none.

Returns:

Returns an MKScore.

See also:

-- addToScore:, -- removeFromScore

- (MKNote *) infoNote

Returns the MKPart's info MKNote.

Returns:

Returns an MKNote.

See also:

-- setInfoNote:

- (void) setInfoNote:

(MKNote *)

aNote

Sets the MKPart's info MKNote to a copy of aNote.

Parameters:

aNote

is an MKNote. The info MKNote can be given information (as parameters) that helps define how the MKPart should be interpreted; in particular, special MusicKit parameters (more accurately, parameter tags) are by convention used in a MKPart info MKNote. Listed below, these parameters pertain to the manner in which the MKNotes in the MKPart are synthesized, although as with any MKNote, the info MKNote's parameters must be read and applied by some other object (or your application) in order for them to have an effect. Keep in mind that the info MKNote is be no means restricted to containing only these parameters:

Parameter Tag	Expected Value	Typical Use
MK_synthPatch	MKSynthPatch subclass	Argument to MKSynthInstrument's setSynthPatchClass: method.
MK_synthPatchCount	integer	Argument to MKSynthInstrument's setSynthPatchCount: method.
MK_midiChan	integer	Argument to MKMidi's channelNoteReceiver: method.
MK_track	integer	Automatically set when a midifile is read into a MKScore.

The info MKNote is stored separately from the MKPart's main body of MKNotes; methods such as empty don't affect it.

See also:

-- infoNote

- (NSString *) partName

Return the name of the receiver.

Returns:

Returns an NSString instance.

- (void) setPartName:

(NSString *)

newPartName

Assigns the name of the receiver.

Parameters:

newPartName

An NSString for the new name of the part. The part name is used when reading and writing parts to a Scorefile.

---

Member Data Documentation

- (MKScore*) score [protected]

The score to which this MKPart belongs.

- (NSMutableArray*) notes [protected]

NSArray of MKNotes.

- (MKNote*) info [protected]

A MKNote used to store an arbitrary collection of info associated with the MKPart.

- (unsigned int) noteCount [protected]

Number of MKNotes in the MKPart.

- (BOOL) isSorted [protected]

YES if the receiver is sorted.

---

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

• MKPart.h