back to main

Introduction to NWC2 User Tools PHP Scripting

Introduction:

This introduction shows you how to perform automation on musical entities within a single stave inside an NWC2 file using a PHP script. For example, if you wish to transpose chords, replace one type of entity e.g. text with another type of entity e.g. dynamic, transform chords into arppegiations, remove bottom notes from a chord, etc, all these can be achieved through PHP scripting.

Prerequisites:

You will need the following for this introduction:
  1. NoteWorthy Composer 2.5 or above
  2. Microsoft Visual C++ 2008 Redistributable Setup (vcredist_x86.exe) installed on Windows XP or above
  3. NWC2 User Tools installed on Windows XP or above (requires the above two pre-installed)
  4. Understanding of PHP
Note that you do not need to install PHP on your computer separately.

What is NWCTxt?

NWCTxt is the NWC2 entities of an NWC file rendered into human-friendly code. There a chord containing 3 notes on the treble stave with time value 4th (crotchet) is rendered as "|Chord|Dur:4th|Pos:-6o,-4o,-2o|Color:0|Visibility:Default". Each entity must occupy a separate line, and must start with its entity type, which is always the first field in the pipe-symbol '|' delimited line. In this case, the entity type is "Chord". The following fields are the various options within this entity line. "Dur:4th" represents duration of a 4th (crotchet), "Pos:-6o,-4o,-2o" represent note positions 6, 4 and 2 under the central stave line (B above middle C on the treble clef). The other options "Color:" and "Visibility:" are fairly self-explanatory. From NWC2.5, an NWC can be saved either as a binary NWC file or a NWCTxt textfile.

How to Run a PHP Script in NWC2:

  1. After installing NWC2 and NWC2 User Tools on Windows XP or above, select Tools->User Tool... (or press Alt+F8) from the main menu in NWC2.
  2. Select New in the pop-up dialog, and then select Browse in the pop-up dialog.
  3. In the Browse pop-up dialog, select nwsw_About.php, and then select Open
  4. In the Browse dialog, select OK
  5. In the User Tool dialog, select Run
  6. The nwsw_About.php script outputs the details of your NWC2 version, and the PHP version info in a dialog box.
  7. To rerun the last php script, simply type Alt+Ctrl+F8 or select Tools->Repeat from NWC2.

Basic Structure of a NWC2 User Tool PHP Script:

The PHP Script applies data manipulation to the current stave inside the NWC2 program from the "Tools->User Tool..." option off the main menu. It must read in the entire current stave from the clipboard (STDIN) in NWCTxt text format, perhap data manipulation as it sequentially parses through each entity in a for loop, and output the result data in NWCTxt text format back to the clipboard (STDOUT) using the echo command. The following lists the stages of a NWC2 User Tool PHP Script.
  1. Include the NWC2Clips library
  2. Instantiate the NWC2Clip object
  3. Populate the NWC2Clip object with the current stave's NWCTxt
  4. Parse through each item within the NWC2Clip object, i.e. each item in the current stave
  5. Instantiate each item's object as it is being parsed for data handling
  6. Test for the current item's value
  7. Perform manipulation on current item if a certain value found
  8. If not found, output item without manipulation
  9. Remove the current item instantiation after each manipulation
  10. At end of stave, insert clip footer
  11. exit script

Example 1: Replace all text entities on the current stave with a note

<?
require_once("lib/nwc2clips.inc");    //<1-Include the NWC2Clips library

$clip = new NWC2Clip('php://stdin'); //<2-Instantiate the NWC2Clip object

echo $clip->GetClipHeader()."\n";    //<3-Populate the NWC2Clip object with the current stave's NWCTxt

foreach ($clip->Items as $item){          //<4-Parse through each item within the NWC2Clip object, i.e. the current stave
	$o = new NWC2ClipItem($item);    //<5-Instantiate each item's object as it is being parsed for data handling
	if ($o->GetObjType() == "Text"){ //<6-Test for the current item's value
           echo "|Chord|Dur:4th|Pos:-2o|Color:0|Visibility:Default\n"; //<7-Perform manipulation on current item if value found
	}else {
          echo $item ;                  //<8-if not found output item without manipulation
        }
	unset($o); //<9-Remove the current item instantiation after each manipulation
}

echo NWC2_ENDCLIP."\n"; //<10-At end of stave, insert clip footer

exit (NWC2RC_SUCCESS) ; //<11-exit script
?>
The above script displays the steps that make up a basic NWC2 User Tool PHP script for nwctxt item manipulation. To run this script, simply follow these steps:
  1. Copy and above text and paste into Notepad
  2. Save the file onto your local drive
  3. In NWC2, press 'x' to insert text entities into your current stave.
  4. Press Alt+F8 to open the User Tools dialog, then select New, and then Browse
  5. Locate the location of your file and select Open. Select OK, and then Run.
  6. All the text entities on your current stave are now replaced by single notes.
  7. Press 'x' again to insert further text entities.
  8. Simply press Alt+Ctrl+F8 to repeat the last User Tool action, i.e. replace text with notes.

Example 2: Insert an Entity at Current Cursor Position

The NWC2Clip object represents contents of the staff that has been copied into the php standard input. When any part of the staff has been selected, it contains only the contents of the selection in nwctxt. When no part of the staff is selected, it contains the entire staff. This dual characteristic provides the developer with the ability to manipulate only a small section of the staff that has been selected, or the entirety of the staff. The following example displays how to insert an entity at the current cursor position by making use of the NWC2Clip contents from selection. This technique allows entities to be inserted, and manipulations to be carried out at a specific location in the staff without having to reload the entire staff. It does not require a change of code, but simply a change of usage.
  1. In NWC2, press Alt+A to add a new blank staff
  2. Insert 2 measures with 4 notes in each measure on the new staff
  3. In the first measure, insert the text expression "1"
  4. In the second measure, insert the text expression "2"
  5. Select the entire contents of the second measure, and press Ctrl+Alt+F8 to rerun the script from Example 1
  6. The script converts the text expression with "2" to a note, and ignores the first text expression because it was not in the selection
The above technique is useful for performing local manipulations on specifically selected entities at the current cursor position, instead of applying global changes to the staff.

Example 3: Adding User Interaction to your User Tool

The WScript.Shell object which is part of the Windows operating system allows the developer to add user interaction to the User Tool script, through the Popup function. The following line instantiates the WScript.Shell object: 
$wso=new COM("WScript.Shell");
The following line displays an message alert from within the User Tool script: 
$wso->Popup("show this message");
The full syntax of the Popup function is provided below (optional parameters in square brackets): 
$return_value = $wso->Popup( $text [, $timeout, $title, $options] );
$return_value: -1=None (timed out); 1=OK; 2=Cancel; 3=Abort; 4=Retry; 5=Ignore; 6=Yes; 7=No;
$text: "display text"
$timeout: pop-up self-closes after specified number of seconds
$options: specified by adding button and icon values together
button values: 0=OK; 1=OK, Cancel; 2=Abort, Ignore, Retry; 3=Yes, No, Cancel; 4=Yes, No; 5=Retry, Cancel
Icon values: 0=None; 16=Critical; 32=Question; 48=Exclamation; 64=Information
The following example adds an alert function the script from Example 1.
  1. In the PHP script from example 1, add the line "$wso=new COM('WSCript.Shell');
  2. At the end of the script, above the "?>" line, add the following line: "function alert($msg){ global $wso; $wso->Popup($msg);}"
  3. Underneasth the $wso instantiation line added in step 1 above, add the line: "alert('press OK to start');"
  4. Save the script, and run it from the User Tools menu. It now displays a message. This is useful for debugging etc.

Example 4: Building an optional PHP Add-on to your User Tool

People use NWC2 differently according to what they are doing. For example, a songwriter has different requirements to a symphonist. A composer has different requirements to a music transcriber. It is therefore useful to be able to build optional add-ons in PHP in order to add specialist tools as required, whilst at the same time providing general functionalities in such a way that avoids duplication of code. The following example provides a walkthru on how this can be achieved.
  1. In "C:\\" create a new textfile called "advanced_tools.php". In advanced_tools.php, insert the following lines: 
    <?
function advanced_tools_main(){
  alert("you are in advanced_tools_main");
}

?>
  2. Save "C:\advanced_tools.php"
  3. Open the PHP User Tool script amended in Example 3. Above the $wso instanstiation line, add the follwing line: 
    if (file_exists("C:\\advanced_tools.php")) require_once("advanced_tools.php");
  4. Under the $wso instantiation line, add the following line: 
    if (function_exists("advanced_tools_main")) advanced_tools_main();
  5. Save the file, and run the script. It displays the message "you are in advanced_tools_main".
  6. Rename "C:\advanced_tools.php" to "C:\_advanced_tools.php"
  7. Rerun the User Tool Script. Notice that this time it does not display the message, and does not throw at error at the absence of advanced_tools.php.