JavaScript in QC3

From QuartzCompositions.com the central source for Quartz Composer :: wiki

This page is for the JavaScript patch in Quartz Composer 3 (Mac OS X 10.5 or higher) only. For JavaScript patch in earlier versions, see JavaScript.

The QC3 JavaScript patch offers better support for standard JavaScript syntax over earlier versions, and allows you to name your inputs and outputs.

Table of contents

1 Changes from QC2 to QC3 2 The main() function 3 Inputs and outputs 3.1 Types for all variables 3.2 Returning values as outputs 4 _testMode

Changes from QC2 to QC3

The major changes in the new version are as follows:

• Your code is now placed inside a main() function. Other functions can be defined in the same patch, allowing you to modularise your code better than before.
• Inputs and outputs are named according to the parameter list of your main() function
• Inputs and outputs are typed properly, making it easier to ensure data integrity as it is processed by your code
• Your code is executed first time round in _testMode for syntax checking. In test mode, all inputs are null so these must be caught to avoid compilation errors.

The main() function

The main body of your code should be defined as a function called main(). Doing this allows you to name and type your inputs and outputs, and make a clearer distinction between global (persistent) and local (temporary) variables, as well as giving you the opportunity to add other functions as needed.

var i = 0;

function (__string biography, __number contestantNumber) main (__string name, __number age, __boolean canWhistle)
{
   i++;
   var result = new Object();
   result.biography = "Contestant number " + i + " is " + name +
      ", who is " + age + " years old" + whistlingSummary(canWhistle);
   result.contestantNumber = i;
   return result;
}

function whistlingSummary (__boolean canWhistle) {
   if (canWhistle) {
      return " and can whistle";
   } else {
      return " but can't whistle";
   }
}

In the example above, i is a persistent global variable (it is incremented each time the JS patch executes, including once at compile time).

Inputs and outputs

All inputs and outputs are defined using one of the following types and given a proper name.

Types for all variables

__boolean	A simple boolean variable, evaluating to true or false
__index	An integer number
__number	Any number
__string	A string
__image	Allows you to pass an image through a JavaScript function, although you cannot do any pixel processing on the image. It is possible to get the image dimensions using .extent.width and .extent.height
__structure	Treated as Array objects, structures can be passed to and from JavaScript patches. A structure's length can be obtained using .length. Elements can be obtained as with a typical JavaScript array, ie anArray[3] for index elements, and anArray.propertyName for associative arrays (keyed structures)
__virtual	A metatype

Returning values as outputs

Since it is possible to return multiple values from a single function, the return value must be of the type Object. In your main() function you need to create a temporary Object, and assign it's properties using the same names as the outputs defined in the function.

function (__string message, __number phoneNumber) main () {
   myResult = new Object;
   myResult.message = "Hello World";
   myResult.phoneNumber = 5551234;
   return myResult;
}

_testMode

Your JavaScript code is always executed first in a test mode which is used to check the syntax of your code. In test mode, the global variable _testMode equals true and all inputs to your main() function will be null. This means that any processing of inputs that are beyond simple types (eg. iterating over a structure) will fail.

To handle this, check that _testMode is false before doing anything advanced:

function (__number elementCount) main (__structure inputStructure) {
   result = new Object;
   if (!_testMode) {
      result.elementCount = inputStructure.length;
   }
   return result;
}