Release notes for Scriptographer 2.5.031

Tools and scripts

• We've reduced the tool buttons to a single pen button, which is colored when a tool script has been played.
• In the scripts list you can now identify if a script is a mouse tool.
• To start a tool or a script, select it and press on the play button.
• The scripts refresh button has been removed: the scripts list is automatically refreshed when you add a new script to your scripts folder.

New scripts included with Scriptographer 2.5

• clouds.js & wave.js

Two simple drawing tools

• colorizer.js

Select an image and a bunch of paths which are on top of the image. The paths are colored according to the average color of the pixels within their shape.

Website scripts

All scripts on Scriptographer.com have been rewritten to incorporate the changes made to the Scriptographer API.
Please check your scripts to see if they are still working the way they are supposed to. (The old scripts are still there, marked with '-previous' in there name.)

Reference

We've put a lot of work into improving the API reference.
The classes are now ordered in a more logical way.
All unnecessary classes, properties and functions have been hidden from view.
Most functions and properties include descriptions on what they do and often include sample code explaining how to work with them.

Properties

• All getters and setters have been converted to properties.
• Properties can now be set directly when creating a new object by using a block after the constructor:

Before:

var circle = new Path.Circle(new Point(10, 10), 10);
circle.fillColor = new GrayColor(1);
circle.strokeColor = new GrayColor(1);

Now:

new Path.Circle(new Point(10, 10), 10) {
	fillColor: new GrayColor(1),
	strokeColor: new GrayColor(1)
}

No more Class.STATIC_PROPERTY like properties

Most static properties can now be set with strings, instead of pointing to static properties containing numbers:

Before:

var circle = document.createCircle(new Point(50, 50), 10); 
print(circle.blendMode); // 1

// Change the blend mode of the path item: 
circle.blendMode = Art.BLEND_MULTIPLY;

Now:

var circle = new Path.Circle(new Point(50, 50), 10); 
print(circle.blendMode); // 'normal'

// Change the blend mode of the path item:
circle.blendMode = 'multiply';

Number

• Extra functions for the Number prototype:

number.isEven() // returns true if the number is even, false otherwise
number.isOdd() // returns true if the number is odd, false otherwise
number.toDegrees() // converts the number from radians to degrees
number.toRadians() // converts the number from degrees to radians
number.format(str) // converts the number to a formatted string using the java.text.DecimalFormat system

Arithmetic operators

• Point and Size objects can now use arithmetic operators:

var point = new Point(10, 4);

// Addition:
print(point + point) // { x: 20.0, y: 8.0 }

// Multiplication by an array
print(point * [1, 2]) // { x: 10.0, y: 8.0 }

// Multiplication by a number
print(point * 2) // { x: 20.0, y: 8.0 }

// Division by a number
print(point / 2) // { x: 5.0, y: 2.0 }

// Division by a point
print(point / point) // { x: 1.0, y: 1.0 }

var size = new Size(10, 20);

// Adding a size to a point
print(point + size) // {x: 20, y: 24}

// Adding a point to a size
print(size + point) // {width: 20, height: 24}

// How it was done before:
var point = (new Point(50, 40).multiply(20)).subtract(new Point(5, 5).divide(3));

// How it is done now:
var point = new Point(50, 20) * 20 - new Point(5, 5) / 3;

Point & Size

• Extra round(), ceil(), floor() and abs() math functions have been added to the Point, Size and Rectangle prototypes:

var point = new Point(-10, -5);
point = point.abs();
print(point) // { x: 10, y: 5 }

We've added a random() function to Point and Size:

// create a point with random x
// and y values between 0 and 10
var point = new Point(10, 10) * Point.random();

Rectangle

• Rectangle has some new properties:

rightCenter - the right center point of the rectangle
leftCenter - the left center point of the rectangle
topCenter - the top center point of the rectangle
bottomCenter - the bottom center point of the rectangle

Item

• Art has now been renamed to Item
• toSource(): Calling the toSource() function on an item will print out the source code needed to construct that item and its children to the console.
• We've added a position property to Item, which makes it easier to move items to absolute positions.

var path = document.selectedItems.first;
// moves the center point of the path to x: 10, y: 20
path.position = new Point(10, 20);

// moves the path by {x: 10, y: 10}:
path.position += 10;

• append(item) has been replaced with appendTop(item) and appendBottom(item)

appendTop(item) inserts the specified item as a child of the item by appending it to the list of children and moving it above all other children.
appendBottom(item) inserts the specified item as a child of the item by appending it to the list of children and moving it below all other children.

• the geometricBounds property has been removed from Item since it was the same as the bounds property

Path

• New constructors for geometric shapes, which replace the old document.createXXXX functions:

Path.Line(pt1, pt2)
Path.Line(x1, y1, x2, y2)
Path.Rectangle(rectangle)
Path.Rectangle(x, y, width, height)
Path.RoundRectangle(rectangle, hor, ver)
Path.Oval(rect)
Path.Oval(rect, circumscribed)
Path.Oval(rect, circumscribed)
Path.RegularPolygon(center, numSides, radius)
Path.Star(center, num{Points, radius1, radius2)
Path.Spiral(firstArcCenter, start, decayPercent, numQuarterTurns, clockwiseFromOutside)
Path.Circle(x, y, width, height)
Path.Circle(x, y, width, height, circumscribed)
Path.Circle(center, radius)
Path.Circle(x, y, radius)

Sample code:

// create a circle at x: 10, y: 10 with a radius of 5
var circle = new Path.Circle(10, 10, 5);

// create a line from x: 5, y: 10 to x: 10, y: 20
var firstPoint = new Point(5, 10);
var secondPoint = new Point(10, 20);
var line = new Path.Line(firstPoint, secondPoint);

• new arcTo() function for drawing half circles
• lineto() can now called straight after creating a new Path, without having to call moveTo() before:

var path;
function onMouseDown(event) {
	path = new Path();
}

function onMouseDrag(event) {
	path.lineTo(event.point);
}

Color

• Colors values are converted automatically in the background when getting channel values:

For example, getting the gray channel of an RGB color now works without having to convert it:

var red = new RGBColor(0, 0, 0);
print(red.gray); // '1'

GradientColor

• GradientColor has been simplified, allowing you to set gradients by specifying origin and destination points.

// a radial gradient from white to black
var gradient = new Gradient() {
	type: 'radial',
	stops: [
		new GradientStop(new GrayColor(0), 0),
		new GradientStop(new GrayColor(1), 1)
	]
};
var origin = new Point(0, 0);
var destination = new Point(0, 100);
var gradientColor = new GradientColor(gradient, origin, destination);

// create a circle filled with the gradient color
var circle = new Path.Circle(new Point(0, 0), 100) {
	fillColor: gradientColor
};

Path Style

• FillStyle and StrokeStyle have been combined into PathStyle:

var path = new Path();
path.style = {
	fillColor: new RGBColor(1, 0, 0),
	strokeColor: new RGBColor(0, 1, 0)
}

• Fill and stroke properties can now also be set directly on an item:

var path = new Path();
path.fillColor = new RGBColor(1, 0, 0);
path.strokeWidth = 3;
path.strokeColor = new RGBColor(0, 1, 0);

Document

• getMatchingItems() has been renamed to getItems() and can filter results based on item type:

// All selected paths and rasters contained in the document.
var selectedItems = document.getItems({ 
    type: [Path, Raster], 
    selected: true
});

// All hidden Paths contained in the document.
var hiddenItems = document.getItems({
    type: Path,
    hidden: true
});

• Current Style

The currentStyle property of Document reflects the currently active Illustrator path style.
All selected items and newly created items will be styled using the document.currentStyle path style.

Artboard

• We've added support for creating and editing art boards in the CS4 version of Scriptographer with the new Artboard class.

Tool

• The onInit() function has been deprecated.
• We added a couple of extra properties to the event object which is sent with the mouse events:

event.lastPoint - the position of the mouse when the last event was fired
event.delta - the vector of the mouse movement between event.point and event.lastPoint
event.count - the amount of events received by the mouse event handler

Example of a small Zigzag tool using event.delta and event.count:

var path;
function onMouseDown(event) {
	// Create a new path every time the mouse is pressed
	path = new Path();
}

function onMouseDrag(event) {
	var rotation = event.count.isOdd() ? 90 : -90;
	var vector = event.delta.rotate(rotation.toRadians());
	path.lineTo(event.point + vector);
}

• setDistanceThreshold(pt) and setEventInterval(ms) have been converted to properties and have been moved to tool:

onMouseDrag is only fired after the mouse has moved at least 10 points:

tool.distanceThreshold = 10;

onMouseDrag is fired every second while the mouse is down:

tool.eventInterval = 1000;

UI

• Static and ImageStatic have been renamed to TextPane and ImagePane
• TextPane items are resized to their correct size automatically now, making this a thing of the past: