NoteWorthy Composer 2 includes a new User Tool facility.
- NWC2 User Tool Starter Kit Download Page (http://ntworthy.com/nwc2/usertools/)
Some facts about the User Tool facility:
- User Tools are accessed from the Tools, User Tool command, or from the keyboard using Alt+F8.
- A User Tool processes notation contained in a single staff, or selected portion of a staff.
- When a User Tool is invoked, NWC2 passes a text description of the staff notation to the tool. This text is commonly called NWC2 Clip Text. Each line of text represents a single object on the NWC2 staff, such as a chord, note, text expression, or tempo item.
- Each User Tool is actually a stand alone program or script that accepts NWC2 Clip Text as input, and can output new or updated Clip Text back to NWC2.
- NWC2 fully supports the User Tool mechanism out of the box, but it does not come prepackaged with any actual tools. A starter kit built around the PHP scripting language can be downloaded from this topic.
If you are already using NWC2, then the easiest way to get started with the User Tool facility is by downloading and installing the NWC2 User Tool Starter Kit (http://ntworthy.com/nwc2/usertools/). It will automatically detect your existing copy of NWC2 and setup a set of scripts for immediate use.
The starter kit includes the following tools:
- About Starter Kit (nwsw)
This script simply displays a message describing the start kit and the currently installed version of the utility library.
- Arpeggiate (nwsw)
This script adds leading grace notes into selected quarter, half, or whole note chords in order to create an arpeggio sound effect during play back.
- Retrograde (nwsw)
This script is used to retrograde selected notation in a staff.
- Statistics (nwsw)
This simple script counts the items in the selection and reports back the results.
- Unjazzify (nwsw)
This script will find note pairs where the first note is a dotted note, and the second is half the notehead duration of the first and is not dotted. It will convert the pair into two notes of equal duration.
- Variable Dump for Developers (nwsw)
Targetted at script writers, this script enables a developer to explore the array tree built by the nwc2clips.inc library included in this package.
The starter kit also includes the following scripts from Andrew Purdam:
- Compound Autobeam (adp)
Beams complex time sigs according to user-specified template.
- Global Modification (adp)
Permits you to globally modify particular components in a staff.
- Parts (adp)
Permits you to separate a part in polyphony.
- Ranges (adp)
Script that returns the note ranges in a selection.
- Transpose Chords (adp)
A script which will automatically transpose chords written as text.
This example demonstrates prompting for data before invoking a User Tool.
The actual tool script looks like this:
<?php
// nwsw_PromptExample.php Version 1.0
//
// This script demonstrates the prompting mechanism in NWC2 User Tools.
//
// Copyright © 2004 by NoteWorthy Software, Inc.
// All Rights Reserved
//
// History:
// 2004-12-12: Initial release (1.0)
//
require_once("lib/nwc2clips.inc");
$clip = new NWC2Clip('php://stdin');
$raw_argv = print_r($argv,true);
echo <<<___EOTEXT
This script demonstrates one method for passing command line
arguments into a user tool. This demonstration accepts three
options, each of which are prompted on the scripts behalf
by NWC2.
The built-in argc and argv variables are set as follows:
\$argc = $argc
\$argv = $raw_argv
The result of the example processing of the options is
shown below. To see how this was done, simply look at
the source for this script.
___EOTEXT;
// Below is an example of one technique for evaluating the arguments passed
// to the script
$opts = array();
foreach ($argv as $k => $v) {
if (!$k) continue;
if (preg_match('/^\/(opt[1-3])\=(.*)$/',$v,$m)) {
$optname = $m[1];
$optvalue = $m[2];
$opts[$optname] = $optvalue;
}
}
if (isset($opts["opt1"])) {
echo "\nOption 1 is set with the following data: $opts[opt1]\n";
}
if (isset($opts["opt2"])) {
echo "\nOption 2 is set with the following data: $opts[opt2]\n";
}
if (isset($opts["opt3"])) {
echo "\nOption 3 is set with the following data: $opts[opt3]\n";
}
exit(NWC2RC_REPORT);
?>
The Command used in the NWC2 User Tool Description is as follows:
'php\php.exe scripts\nwsw_PromptExample.php "/opt1=<PROMPT:Prompt 1: Select an option from this list:=|Quarter|8th|16th|32nd>" "/opt2=<PROMPT:Prompt 2: Enter a number=#[0,15]>" "/opt3=<PROMPT:Prompt3: Enter some text=*>"'
I was going to ask this but discovered myself (aint I smart? :D) and wanted to share:
So you have quite a few user tool scripts with various parametres stored under your Tools > User Tool... dialogue as I do? Probably you'd like to to make a backup of them now and then. But how? So simple.
They are stored in a plain text file named nwc2UserTools.ini under the directory defined in Tools > Options > Folders > Config Files, which is by default \NoteWorthy Composer 2\Config.
Backup that file. :)
PS: Thanks Eric, updated per your post (https://forum.noteworthycomposer.com/?topic=5537.msg36107#msg36107)!
More precisely, the User Tool setttings are stored in the folder located by Tools, Options, Folders, Config Files.
Version 1.13 of the NWC2 User Tool Starter Kit (http://ntworthy.com/nwc2/usertools/) has now been released. It includes minor updates to many of the scripts.
So...I'm trying to download the User Tools, v1.21, and it tells me my NWC is either not installed or has been altered since installation.
Duh...I've kept up with the updates to the 2.x beta.
It's not a Firefox issue, I've tried IE and Firefox both. Is there something else I'm missing somewhere??
HELP!
steve
This error means that the NWC2 uninstall information does not point to the correct NWC2 program files location. There are two possible causes for this (assuming you actually have NWC2 installed):
- You manually moved the NWC2 program files from the original location where they were installed.
- You manually removed the NWC2 uninstall key from the registry.
You can correct this by reinstalling NWC2 or by manually correcting the folder paths found in the following registry area:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\NoteWorthy Composer 2
Can I put comments into a clip text file? It would help diagnosis a lot. And what happens to SYSERR if the script completes OK?
Here are some links that might help:
- Working with *.nwctxt files (https://forum.noteworthycomposer.com/?topic=6094)
- User Tool Command (http://ntworthy.com/nwc2/help/MNU_USERTOOLS.htm)
Yes. They will display in the STDOUT popup, but they are discarded when STDOUT is parsed back into the song.
Some further discussion <here> (https://forum.noteworthycomposer.com/?topic=6246.msg42086#msg42086).
If the script completes OK, there can be no SYSERR. One shouldn't care about what happens to it.
Noteworthy Online - Thank you; I should have found this; I am an idiot; thank you for not telling me so.
Rick G - You are a better coder than me. I often find that the script finishes, but produces something different from what I expected. Without some means of monitoring flow and checking values of variables it is hard to find the bug. Thank you, though.
If you are coding in JScript or VBScript, I may be able to help.
Put
WScript.Quit(99) where your program ends. This will cause NWC2 to display STDOUT to you (comments and all). Comment out the line or change it to:
WScript.Quit(0) to test normal operation.
In JScript, I declare an array (e.g.,
var a = [];) and push things I'm interested in on to it.
At program end, I use:
WScript.Echo(a.join("\n"));
One possible use of the new "Run User Tool" tool is to aid in new user tool testing/debugging.
If you run your new clip script via the "RUT" tool, and you check the box to "Display summary of changes, if user tool returns success", then you will see a NWCTXT "delta" of the changes that your script made. The delta for each staff is shown in turn separately. At any point, you can make "backdoor" changes to your script, then do a "back" and a "next" in RUT, and see the new results of your script, all without leaving the RUT environment. Once happy with the changes, you can proceed out of RUT and see your changes applied within NWC2.
The RUT user tool entry to invoke your new user tool could have a command like this:
php\php.exe scripts\prw_RunUserTool.wxphp display all "<yourtoolname>"
The display pre-checks the box to display summaries of changes, and the all says to do all staffs in turn. Make sure to set an "Input Type" of "File Text", and check the options "Returns File Text" and "Prompts for User Input".
I am trying to create tool that allows the user to enter a specific entity such as an instrument change, clef, dynamic or barline at the current cursor position. I looked at the examples in the User Tools and they all seem to apply changes to the entire file, or a selection of notes. Is there any way of inserting a specific entity at the cursor position?
It is possible by requiring File text and returning File text. NWC will prompt you to save your work since the change cannot be undone :(
More discussion at: Insert entity at current cursor position working example (https://forum.noteworthycomposer.com/?topic=8312.0).