MusicKit  0.0.0
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>


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:

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

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

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.


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