I may be the only one who missed this, but thought I'd share just in case...
There is a new parameter now for NWC2ClipItem:
function NWC2ClipItem($itemtext,$remapFakes=false)
You may have tools (like I do) that still call NWC2ClipItem without a second parameter. This defaults it to false, and causes a strange behaviour, that took me a while to track down. I usually use my user tools on an entire staff, and hence there are no "fake" items, and it still works. But I just tried to run one on a partial clip, and it wouldn't work.
Without the "remapFakes", the fake objects are not processed by NWC2PlayContext. In my case, the clef defaulted to treble, even though the clip was bass clef, and a fake object indicated so. Adding a second parameter of true for NWC2ClipItem fixed my problem. Not sure why you'd ever want to disable the "fake mapping", such that perhaps the default should have been true? Perhaps there was a fear of breaking legacy kludges that worked around the absence of the much cleaner fake items.
I see Peter for one has a tool with the new parameter:
https://forum.noteworthycomposer.com/?topic=7209
Note that the "variable dump for developers" user tool was updated to do the remap fakes. So if you dump a clip, the fake items will look good, but if you run your script on the same clip, it will get fed fake items that are not like what the dump showed you. Your tool may well ignore these malformed fake items, but the update-play-context will also ignore them.
Everyone else seems to be having no trouble with this, but I'm still struggling with it! It turns out that you should add the second parameter as true
if and only if you are making use of a NWC2PlayContext object.
- If you are not making use of a NWC2PlayContext object, you must not add the second parameter (or you can add it as false if you want to). Otherwise, your script will process objects that occured earlier in the measure of the selected object(s), even though they were not selected! [NWC now seems to provide as "context" all of the notes in a measure prior to the selection start.]
- If you are making use of a NWC2PlayContext object, you must add the second parameter as true. Otherwise, your script will not process context information to correctly set your clef, key, bar, etc, when the selection is a partial staff. In this case, you must also make sure that your script does not process the remapped fake objects, other than using them to update the context! Otherwise, your script will operate on objects that were not selected (but were earlier in the same measure of the selection). A template:
foreach ($clip->Items as $item) {
$o = new NWC2ClipItem($item, true);
if ($o->IsContextInfo()) {
$pc->UpdateContext($o);
continue;
}
<your script processing here>
$pc->UpdateContext($o);
}
I think NWSW has updated all of its user tools accordingly. And perhaps I am the only other user to make use of play-context objects so far?!
When writing a new script targeted at NWC 2.1 or later, one of the first things to consider is how to deal with context information when the selection starts in the middle of a staff.
Version 2.1 of the NWC2 User Tool Starter Kit library allows older scripts designed to run in NWC 2.0 (that are not "fake item" aware) to be used without any modification. The $remapFakes option is provided as one method for processing context information just as if the context objects are actually in the clip, but this should only be done with newer scripts that are aware of the fake context items. This can greatly simplify the process of handling context information in a new script.
If you are starting a new PHP based script for NWC 2.1, it is almost always easier to enable the $remapFakes option. If you add notation items, or do something like create lyric text for the clip, then the context items should almost always be skipped during this process, since they are not actually part of the selection. This is generally done using the $o->IsContextInfo() property of the object. For example, the nwsw_NoteNames.php script handles context items only for purposes of updating the play context, but then ignores them when constructing the output stream that includes note names.
Each tool is likely to have different needs in this regard.