scratchfoundation/paper.js
1
0
Fork 0
mirror of https://github.com/scratchfoundation/paper.js.git synced 2025-05-20 01:31:36 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Documentation: rearrange @example tags, improve examples, rename boolean -> Boolean and misc smaller edits.

Browse source
This commit is contained in:
Jonathan Puckey 2011-05-30 19:42:17 +02:00
parent 16f521b8a2
commit 17fcb923ff
23 changed files with 727 additions and 481 deletions

4
src/basic/Line.js
View file

@ -23,7 +23,7 @@ var Line = this.Line = Base.extend({
*
* @param {Point} point1
* @param {Point} point2
* @param {boolean} [infinite=true]
* @param {Boolean} [infinite=true]
*
* @class The Line object represents..
* @constructs Line
@ -65,7 +65,7 @@ var Line = this.Line = Base.extend({
* Specifies whether the line extends infinitely
*
* @name Line#infinite
* @type boolean
* @type Boolean
*/
/**

6
src/basic/Matrix.js
View file

@ -381,7 +381,7 @@ var Matrix = this.Matrix = Base.extend({
},
/**
* @return {boolean} Whether this transform is the identity transform.
* @return {Boolean} Whether this transform is the identity transform.
*/
isIdentity: function() {
return this._m00 == 1 && this._m10 == 0 && this._m01 == 0 &&
@ -392,7 +392,7 @@ var Matrix = this.Matrix = Base.extend({
* Returns whether the transform is invertible. A transform is not
* invertible if the determinant is 0 or any value is non-finite or NaN.
*
* @return {boolean} Whether the transform is invertible.
* @return {Boolean} Whether the transform is invertible.
*/
isInvertible: function() {
var det = this.getDeterminant();
@ -404,7 +404,7 @@ var Matrix = this.Matrix = Base.extend({
* Checks whether the matrix is singular or not. Singular matrices cannot be
* inverted.
*
* @return {boolean} Whether the matrix is singular.
* @return {Boolean} Whether the matrix is singular.
*/
isSingular: function() {
return !this.isInvertible();

240
src/basic/Point.js
View file

@ -27,6 +27,12 @@ var Point = this.Point = Base.extend({
* @param {Number} x the x coordinate
* @param {Number} y the y coordinate
*
* @example
* // Create a point at x: 10, y: 5
* var point = new Point(10, 5);
* console.log(point.x); // 10
* console.log(point.y); // 5
*
* @class The Point object represents a point in the two dimensional space
* of the Paper.js project. It is also used to represent two dimensional
* vector objects.
@ -39,21 +45,87 @@ var Point = this.Point = Base.extend({
* console.log(point.y); // 5
* </pre>
*/
/**
* Creates a Point object using the numbers in the given array as
* coordinates.
*
* @name Point#initialize
* @param {array} array
*
* @example
* // Creating a point at x: 10, y: 5 using an array of numbers:
* var array = [10, 5];
* var point = new Point(array);
* console.log(point.x); // 10
* console.log(point.y); // 5
*
* @example
* // Passing an array to a functionality that expects a point:
*
* // Create a circle shaped path at x: 50, y: 50
* // with a radius of 30:
* var path = new Path.Circle([50, 50], 30);
* path.fillColor = 'red';
*
* // Which is the same as doing:
* var path = new Path.Circle(new Point(50, 50), 30);
* path.fillColor = 'red';
*/
/**
* Creates a Point object using the properties in the given object.
*
* @name Point#initialize
* @param {object} object
*
* @example
* // Creating a point using an object literal with length and angle
* // properties:
*
* var point = new Point({
* length: 10,
* angle: 90
* });
* console.log(point.length); // 10
* console.log(point.angle); // 90
*
* @example
* // Creating a point at x: 10, y: 20 using an object literal:
*
* var point = new Point({
* x: 10,
* y: 20
* });
* console.log(point.x); // 10
* console.log(point.y); // 20
*
* @example
* // Passing an object to a functionality that expects a point:
*
* var center = {
* x: 50,
* y: 50
* };
*
* // Creates a circle shaped path at x: 50, y: 50
* // with a radius of 30:
* var path = new Path.Circle(center, 30);
* path.fillColor = 'red';
*/
/**
* Creates a Point object using the width and height values of the given
* Size object.
*
* Sample code:
* <code>
* @name Point#initialize
* @param {Size} size
*
* @example
* // Creating a point using a size object.
*
* // Create a Size with a width of 100pt and a height of 50pt
* var size = new Size(100, 50);
* console.log(size); // { width: 100, height: 50 }
* var point = new Point(size);
* console.log(point); // { x: 100, y: 50 }
* </code>
*
* @name Point#initialize
* @param {Size} size
*/
/**
* Creates a Point object using the coordinates of the given Point object.
@ -113,7 +185,7 @@ var Point = this.Point = Base.extend({
/**
* Returns a copy of the point.
* This is useful as the following code only generates a flat copy:
*
* @example
* var point1 = new Point();
* var point2 = point1;
@ -141,31 +213,31 @@ var Point = this.Point = Base.extend({
* the point as a new point.
* The object itself is not modified!
*
* @example
* var point = new Point(5, 10);
* var result = point + 20;
* console.log(result); // { x: 25.0, y: 30.0 }
*
* @name Point#add
* @function
* @param {Number} number the number to add
* @return {Point} the addition of the point and the value as a new point
*
* @example
* var point = new Point(5, 10);
* var result = point + 20;
* console.log(result); // { x: 25.0, y: 30.0 }
*/
/**
* Returns the addition of the supplied point to the point as a new
* point.
* The object itself is not modified!
*
* @name Point#add
* @function
* @param {Point} point the point to add
* @return {Point} the addition of the two points as a new point
*
* @example
* var point1 = new Point(5, 10);
* var point2 = new Point(10, 20);
* var result = point1 + point2;
* console.log(result); // { x: 15.0, y: 30.0 }
*
* @name Point#add
* @function
* @param {Point} point the point to add
* @return {Point} the addition of the two points as a new point
*/
add: function(point) {
point = Point.read(arguments);
@ -177,31 +249,31 @@ var Point = this.Point = Base.extend({
* the point as a new point.
* The object itself is not modified!
*
* @example
* var point = new Point(10, 20);
* var result = point - 5;
* console.log(result); // { x: 5.0, y: 15.0 }
*
* @name Point#subtract
* @function
* @param {Number} number the number to subtract
* @return {Point} the subtraction of the point and the value as a new point
*
* @example
* var point = new Point(10, 20);
* var result = point - 5;
* console.log(result); // { x: 5.0, y: 15.0 }
*/
/**
* Returns the subtraction of the supplied point to the point as a new
* point.
* The object itself is not modified!
*
* @name Point#subtract
* @function
* @param {Point} point the point to subtract
* @return {Point} the subtraction of the two points as a new point
*
* @example
* var firstPoint = new Point(10, 20);
* var secondPoint = new Point(5, 5);
* var result = firstPoint - secondPoint;
* console.log(result); // { x: 5.0, y: 15.0 }
*
* @name Point#subtract
* @function
* @param {Point} point the point to subtract
* @return {Point} the subtraction of the two points as a new point
*/
subtract: function(point) {
point = Point.read(arguments);
@ -213,31 +285,31 @@ var Point = this.Point = Base.extend({
* the point as a new point.
* The object itself is not modified!
*
* @example
* var point = new Point(10, 20);
* var result = point * 2;
* console.log(result); // { x: 20.0, y: 40.0 }
*
* @name Point#multiply
* @function
* @param {Number} number the number to multiply by
* @return {Point} the multiplication of the point and the value as a new point
*
* @example
* var point = new Point(10, 20);
* var result = point * 2;
* console.log(result); // { x: 20.0, y: 40.0 }
*/
/**
* Returns the multiplication of the supplied point to the point as a new
* point.
* The object itself is not modified!
*
* @name Point#multiply
* @function
* @param {Point} point the point to multiply by
* @return {Point} the multiplication of the two points as a new point
*
* @example
* var firstPoint = new Point(5, 10);
* var secondPoint = new Point(4, 2);
* var result = firstPoint * secondPoint;
* console.log(result); // { x: 20.0, y: 20.0 }
*
* @name Point#multiply
* @function
* @param {Point} point the point to multiply by
* @return {Point} the multiplication of the two points as a new point
*/
multiply: function(point) {
point = Point.read(arguments);
@ -249,31 +321,31 @@ var Point = this.Point = Base.extend({
* the point as a new point.
* The object itself is not modified!
*
* @example
* var point = new Point(10, 20);
* var result = point / 2;
* console.log(result); // { x: 5.0, y: 10.0 }
*
* @name Point#divide
* @function
* @param {Number} number the number to divide by
* @return {Point} the division of the point and the value as a new point
*
* @example
* var point = new Point(10, 20);
* var result = point / 2;
* console.log(result); // { x: 5.0, y: 10.0 }
*/
/**
* Returns the division of the supplied point to the point as a new
* point.
* The object itself is not modified!
*
* @name Point#divide
* @function
* @param {Point} point the point to divide by
* @return {Point} the division of the two points as a new point
*
* @example
* var firstPoint = new Point(8, 10);
* var secondPoint = new Point(2, 5);
* var result = firstPoint / secondPoint;
* console.log(result); // { x: 4.0, y: 2.0 }
*
* @name Point#divide
* @function
* @param {Point} point the point to divide by
* @return {Point} the division of the two points as a new point
*/
divide: function(point) {
point = Point.read(arguments);
@ -284,29 +356,29 @@ var Point = this.Point = Base.extend({
* The modulo operator returns the integer remainders of dividing the point
* by the supplied value as a new point.
*
* @example
* var point = new Point(12, 6);
* console.log(point % 5); // {x: 2, y: 1}
*
* @name Point#modulo
* @function
* @param {Number} value
* @return {Point} the integer remainders of dividing the point by the value
* as a new point
*
* @example
* var point = new Point(12, 6);
* console.log(point % 5); // {x: 2, y: 1}
*/
/**
* The modulo operator returns the integer remainders of dividing the point
* by the supplied value as a new point.
*
* @example
* var point = new Point(12, 6);
* console.log(point % new Point(5, 2)); // {x: 2, y: 0}
*
* @name Point#modulo
* @function
* @param {Point} point
* @return {Point} the integer remainders of dividing the points by each
* other as a new point
*
* @example
* var point = new Point(12, 6);
* console.log(point % new Point(5, 2)); // {x: 2, y: 0}
*/
modulo: function(point) {
point = Point.read(arguments);
@ -485,6 +557,9 @@ var Point = this.Point = Base.extend({
* degrees are in quadrant {@code 3} and angles between 270 and 360 degrees
* are in quadrant {@code 4}.
*
* @type Number
* @bean
*
* @example
* var point = new Point({
* angle: 10,
@ -500,9 +575,6 @@ var Point = this.Point = Base.extend({
*
* point.angle = 280;
* console.log(point.quadrant); // 4
*
* @type Number
* @bean
*/
getQuadrant: function() {
return this.x >= 0 ? this.y >= 0 ? 1 : 4 : this.y >= 0 ? 2 : 3;
@ -551,14 +623,14 @@ var Point = this.Point = Base.extend({
* Checks whether the coordinates of the point are equal to that of the
* supplied point.
*
* @param {Point} point
* @return {Boolean} {@true if the points are equal}
*
* @example
* var point = new Point(5, 10);
* console.log(point == new Point(5, 10)); // true
* console.log(point == new Point(1, 1)); // false
* console.log(point != new Point(1, 1)); // true
*
* @param {Point} point
* @return {boolean} {@true if the points are equal}
*/
equals: function(point) {
point = Point.read(arguments);
@ -571,7 +643,7 @@ var Point = this.Point = Base.extend({
* Checks whether the point is inside the boundaries of the rectangle.
*
* @param {Rectangle} rect the rectangle to check against
* @returns {boolean} {@true if the point is inside the rectangle}
* @returns {Boolean} {@true if the point is inside the rectangle}
*/
isInside: function(rect) {
return rect.contains(this);
@ -582,7 +654,7 @@ var Point = this.Point = Base.extend({
*
* @param {Point} point the point to check against
* @param {Number} tolerance the maximum distance allowed
* @returns {boolean} {@true if it is within the given distance}
* @returns {Boolean} {@true if it is within the given distance}
*/
isClose: function(point, tolerance) {
return this.getDistance(point) < tolerance;
@ -593,7 +665,7 @@ var Point = this.Point = Base.extend({
* another vector.
*
* @param {Point} point the vector to check against
* @returns {boolean} {@true it is parallel}
* @returns {Boolean} {@true it is parallel}
*/
isColinear: function(point) {
return this.cross(point) < Numerical.TOLERANCE;
@ -604,7 +676,7 @@ var Point = this.Point = Base.extend({
* (perpendicular) to another vector.
*
* @param {Point} point the vector to check against
* @returns {boolean} {@true it is orthogonal}
* @returns {Boolean} {@true it is orthogonal}
*/
isOrthogonal: function(point) {
return this.dot(point) < Numerical.TOLERANCE;
@ -613,7 +685,7 @@ var Point = this.Point = Base.extend({
/**
* Checks if this point has both the x and y coordinate set to 0.
*
* @returns {boolean} {@true both x and y are 0}
* @returns {Boolean} {@true both x and y are 0}
*/
isZero: function() {
return this.x == 0 && this.y == 0;
@ -623,7 +695,7 @@ var Point = this.Point = Base.extend({
* Checks if this point has an undefined value for at least one of its
* coordinates.
*
* @returns {boolean} {@true if either x or y are not a number}
* @returns {Boolean} {@true if either x or y are not a number}
*/
isNaN: function() {
return isNaN(this.x) || isNaN(this.y);
@ -679,7 +751,7 @@ var Point = this.Point = Base.extend({
*
* @name Point#selected
* @property
* @return {boolean} {@true the point is selected}
* @return {Boolean} {@true the point is selected}
*/
statics: {
@ -757,14 +829,14 @@ var Point = this.Point = Base.extend({
* Returns a new point with rounded {@link #x} and {@link #y} values. The
* object itself is not modified!
*
* @name Point#round
* @function
* @return {Point}
*
* @example
* var point = new Point(10.2, 10.9);
* var roundPoint = point.round();
* console.log(roundPoint); // { x: 10.0, y: 11.0 }
*
* @name Point#round
* @function
* @return {Point}
*/
/**
@ -772,14 +844,14 @@ var Point = this.Point = Base.extend({
* specified {@link #x} and {@link #y} values. The object itself is not
* modified!
*
* @name Point#ceil
* @function
* @return {Point}
*
* @example
* var point = new Point(10.2, 10.9);
* var ceilPoint = point.ceil();
* console.log(ceilPoint); // { x: 11.0, y: 11.0 }
*
* @name Point#ceil
* @function
* @return {Point}
*/
/**
@ -787,28 +859,28 @@ var Point = this.Point = Base.extend({
* specified {@link #x} and {@link #y} values. The object itself is not
* modified!
*
* @name Point#floor
* @function
* @return {Point}
*
* @example
* var point = new Point(10.2, 10.9);
* var floorPoint = point.floor();
* console.log(floorPoint); // { x: 10.0, y: 10.0 }
*
* @name Point#floor
* @function
* @return {Point}
*/
/**
* Returns a new point with the absolute values of the specified {@link #x}
* and {@link #y} values. The object itself is not modified!
*
* @name Point#abs
* @function
* @return {Point}
*
* @example
* var point = new Point(-5, 10);
* var absPoint = point.abs();
* console.log(absPoint); // { x: 5.0, y: 10.0 }
*
* @name Point#abs
* @function
* @return {Point}
*/
return Base.each(['round', 'ceil', 'floor', 'abs'], function(name) {

10
src/basic/Rectangle.js
View file

@ -352,7 +352,7 @@ var Rectangle = this.Rectangle = Base.extend({
* that of the supplied rectangle.
*
* @param {Rectangle} rect
* @return {boolean} {@true if the rectangles are equal}
* @return {Boolean} {@true if the rectangles are equal}
*/
equals: function(rect) {
rect = Rectangle.read(arguments);
@ -361,7 +361,7 @@ var Rectangle = this.Rectangle = Base.extend({
},
/**
* @return {boolean} {@true the rectangle is empty}
* @return {Boolean} {@true the rectangle is empty}
*/
isEmpty: function() {
return this.width == 0 || this.height == 0;
@ -387,14 +387,14 @@ var Rectangle = this.Rectangle = Base.extend({
* @name Rectangle#contains
* @function
* @param {Point} point the specified point
* @return {boolean} {@true if the point is inside the rectangle's boundary}
* @return {Boolean} {@true if the point is inside the rectangle's boundary}
*/
/**
* Tests if the interior of the rectangle entirely contains the specified
* rectangle.
*
* @param {Rectangle} rect The specified rectangle
* @return {boolean} {@true if the rectangle entirely contains the specified
* @return {Boolean} {@true if the rectangle entirely contains the specified
* rectangle}
*/
contains: function(rect) {
@ -415,7 +415,7 @@ var Rectangle = this.Rectangle = Base.extend({
* another rectangle.
*
* @param {Rectangle} rect the specified rectangle
* @return {boolean} {@true if the rectangle and the specified rectangle
* @return {Boolean} {@true if the rectangle and the specified rectangle
* intersect each other}
*/
intersects: function(rect) {

232
src/basic/Size.js
View file

@ -19,44 +19,78 @@ var Size = this.Size = Base.extend({
// DOCS: improve Size class description
/**
* Creates a Size object using the coordinates of the given Size object.
* Creates a Size object with the given width and height values.
*
* @constructor
* @name Size
* @param {Size} size
* @param {Number} width the width
* @param {Number} height the height
*
* @example
* // Create a size that is 10pt wide and 5pt high
* var size = new Size(10, 5);
* console.log(size.width); // 10
* console.log(size.height); // 5
*
* @class The Size object is used to describe the size of something, through
* its {@link #width} and {@link #height} properties.
*
* Sample code:
* <pre>
* // Create a size that is 10pt wide and 5pt height
* // Create a size that is 10pt wide and 5pt high
* var size = new Size(10, 5);
* console.log(size.width); // 10
* console.log(size.height); // 5
* </pre>
*/
/**
* Creates a Point object using the x and y values of the given Point
* Creates a Size object using the numbers in the given array as
* dimensions.
*
* @name Size#initialize
* @param {array} array
*
* @example
* // Creating a size of width: 320, height: 240 using an array of numbers:
* var array = [320, 240];
* var size = new Point(array);
* console.log(size.width); // 320
* console.log(size.height); // 240
*/
/**
* Creates a Size object using the properties in the given object.
*
* @name Size#initialize
* @param {object} object
*
* @example
* // Creating a size of width: 10, height: 20 using an object literal:
*
* var size = new Size({
* width: 10,
* height: 20
* });
* console.log(size.width); // 10
* console.log(size.height); // 20
*/
/**
* Creates a Size object using the coordinates of the given Size object.
*
* @name Size#initialize
* @param {Size} size
*/
/**
* Creates a Size object using the x and y values of the given Point
* object.
*
* Sample code:
* <code>
* @name Size#initialize
* @param {Point} point
*
* @example
* var point = new Point(50, 50);
* var size = new Size(point);
* console.log(size.width); // 50
* console.log(size.height); // 50
* </code>
*
* @name Size#initialize
* @param {Point} point
*/
/**
* Creates a Size object with the given width and height values.
*
* @name Size#initialize
* @param {Number} width the width
* @param {Number} height the height
*/
initialize: function(arg0, arg1) {
if (arg1 !== undefined) {
@ -117,30 +151,30 @@ var Size = this.Size = Base.extend({
* Returns the addition of the supplied value to the width and height of the
* size as a new size. The object itself is not modified!
*
* @example
* var size = new Size(5, 10);
* var result = size + 20;
* console.log(result); // { width: 25.0, height: 30.0 }
*
* @name Size#add
* @function
* @param {Number} number the number to add
* @return {Size} the addition of the size and the value as a new size
*
* @example
* var size = new Size(5, 10);
* var result = size + 20;
* console.log(result); // { width: 25.0, height: 30.0 }
*/
/**
* Returns the addition of the width and height of the supplied size to the
* size as a new size. The object itself is not modified!
*
* @name Size#add
* @function
* @param {Size} size the size to add
* @return {Size} the addition of the two sizes as a new size
*
* @example
* var size1 = new Size(5, 10);
* var size2 = new Size(10, 20);
* var result = size1 + size2;
* console.log(result); // { width: 15.0, height: 30.0 }
*
* @name Size#add
* @function
* @param {Size} size the size to add
* @return {Size} the addition of the two sizes as a new size
*/
add: function(size) {
size = Size.read(arguments);
@ -152,30 +186,30 @@ var Size = this.Size = Base.extend({
* of the size as a new size. The object itself is not modified!
* The object itself is not modified!
*
* @example
* var size = new Size(10, 20);
* var result = size - 5;
* console.log(result); // { width: 5.0, height: 15.0 }
*
* @name Size#subtract
* @function
* @param {Number} number the number to subtract
* @return {Size} the subtraction of the size and the value as a new size
*
* @example
* var size = new Size(10, 20);
* var result = size - 5;
* console.log(result); // { width: 5.0, height: 15.0 }
*/
/**
* Returns the subtraction of the width and height of the supplied size from
* the size as a new size. The object itself is not modified!
*
* @name Size#subtract
* @function
* @param {Size} size the size to subtract
* @return {Size} the subtraction of the two sizes as a new size
*
* @example
* var firstSize = new Size(10, 20);
* var secondSize = new Size(5, 5);
* var result = firstSize - secondSize;
* console.log(result); // { width: 5.0, height: 15.0 }
*
* @name Size#subtract
* @function
* @param {Size} size the size to subtract
* @return {Size} the subtraction of the two sizes as a new size
*/
subtract: function(size) {
size = Size.read(arguments);
@ -186,30 +220,30 @@ var Size = this.Size = Base.extend({
* Returns the multiplication of the supplied value with the width and
* height of the size as a new size. The object itself is not modified!
*
* @example
* var size = new Size(10, 20);
* var result = size * 2;
* console.log(result); // { width: 20.0, height: 40.0 }
*
* @name Size#multiply
* @function
* @param {Number} number the number to multiply by
* @return {Size} the multiplication of the size and the value as a new size
*
* @example
* var size = new Size(10, 20);
* var result = size * 2;
* console.log(result); // { width: 20.0, height: 40.0 }
*/
/**
* Returns the multiplication of the width and height of the supplied size
* with the size as a new size. The object itself is not modified!
*
* @name Size#multiply
* @function
* @param {Size} size the size to multiply by
* @return {Size} the multiplication of the two sizes as a new size
*
* @example
* var firstSize = new Size(5, 10);
* var secondSize = new Size(4, 2);
* var result = firstSize * secondSize;
* console.log(result); // { width: 20.0, height: 20.0 }
*
* @name Size#multiply
* @function
* @param {Size} size the size to multiply by
* @return {Size} the multiplication of the two sizes as a new size
*/
multiply: function(size) {
size = Size.read(arguments);
@ -220,30 +254,30 @@ var Size = this.Size = Base.extend({
* Returns the division of the supplied value by the width and height of the
* size as a new size. The object itself is not modified!
*
* @example
* var size = new Size(10, 20);
* var result = size / 2;
* console.log(result); // { width: 5.0, height: 10.0 }
*
* @name Size#divide
* @function
* @param {Number} number the number to divide by
* @return {Size} the division of the size and the value as a new size
*
* @example
* var size = new Size(10, 20);
* var result = size / 2;
* console.log(result); // { width: 5.0, height: 10.0 }
*/
/**
* Returns the division of the width and height of the supplied size by the
* size as a new size. The object itself is not modified!
*
* @name Size#divide
* @function
* @param {Size} size the size to divide by
* @return {Size} the division of the two sizes as a new size
*
* @example
* var firstSize = new Size(8, 10);
* var secondSize = new Size(2, 5);
* var result = firstSize / secondSize;
* console.log(result); // { width: 4.0, height: 2.0 }
*
* @name Size#divide
* @function
* @param {Size} size the size to divide by
* @return {Size} the division of the two sizes as a new size
*/
divide: function(size) {
size = Size.read(arguments);
@ -254,29 +288,29 @@ var Size = this.Size = Base.extend({
* The modulo operator returns the integer remainders of dividing the size
* by the supplied value as a new size.
*
* @example
* var size = new Size(12, 6);
* console.log(size % 5); // {width: 2, height: 1}
*
* @name Size#modulo
* @function
* @param {Number} value
* @return {Size} the integer remainders of dividing the size by the value
* as a new size
*
* @example
* var size = new Size(12, 6);
* console.log(size % 5); // {width: 2, height: 1}
*/
/**
* The modulo operator returns the integer remainders of dividing the size
* by the supplied size as a new size.
*
* @example
* var size = new Size(12, 6);
* console.log(size % new Size(5, 2)); // {width: 2, height: 0}
*
* @name Size#modulo
* @function
* @param {Size} size
* @return {Size} the integer remainders of dividing the sizes by each
* other as a new size
*
* @example
* var size = new Size(12, 6);
* console.log(size % new Size(5, 2)); // {width: 2, height: 0}
*/
modulo: function(size) {
size = Size.read(arguments);
@ -290,15 +324,15 @@ var Size = this.Size = Base.extend({
/**
* Checks whether the width and height of the size are equal to those of the
* supplied size.
*
* @param {Size}
* @return {Boolean}
*
* @example
* var size = new Size(5, 10);
* console.log(size == new Size(5, 10)); // true
* console.log(size == new Size(1, 1)); // false
* console.log(size != new Size(1, 1)); // true
*
* @param {Size}
* @return {boolean}
*/
equals: function(size) {
size = Size.read(arguments);
@ -309,7 +343,7 @@ var Size = this.Size = Base.extend({
* {@grouptitle Tests}
* Checks if this size has both the width and height set to 0.
*
* @return {boolean} {@true both width and height are 0}
* @return {Boolean} {@true both width and height are 0}
*/
isZero: function() {
return this.width == 0 && this.width == 0;
@ -318,7 +352,7 @@ var Size = this.Size = Base.extend({
/**
* Checks if the width or the height of the size are NaN.
*
* @return {boolean} {@true if the width or height of the size are NaN}
* @return {Boolean} {@true if the width or height of the size are NaN}
*/
isNaN: function() {
return isNaN(this.width) || isNaN(this.height);
@ -336,16 +370,16 @@ var Size = this.Size = Base.extend({
* Returns a new size object with the smallest {@link #width} and
* {@link #height} of the supplied sizes.
*
* @static
* @param {Size} size1
* @param {Size} size2
* @returns {Size} The newly created size object
*
* @example
* var size1 = new Size(10, 100);
* var size2 = new Size(200, 5);
* var minSize = Size.min(size1, size2);
* console.log(minSize); // { width: 10.0, height: 5.0 }
*
* @static
* @param {Size} size1
* @param {Size} size2
* @returns {Size} The newly created size object
*/
min: function(size1, size2) {
return Size.create(
@ -357,16 +391,16 @@ var Size = this.Size = Base.extend({
* Returns a new size object with the largest {@link #width} and
* {@link #height} of the supplied sizes.
*
* @static
* @param {Size} size1
* @param {Size} size2
* @returns {Size} The newly created size object
*
* @example
* var size1 = new Size(10, 100);
* var size2 = new Size(200, 5);
* var maxSize = Size.max(size1, size2);
* console.log(maxSize); // { width: 200.0, height: 100.0 }
*
* @static
* @param {Size} size1
* @param {Size} size2
* @returns {Size} The newly created size object
*/
max: function(size1, size2) {
return Size.create(
@ -378,13 +412,13 @@ var Size = this.Size = Base.extend({
* Returns a size object with random {@link #width} and {@link #height}
* values between {@code 0} and {@code 1}.
*
* @returns {Size} The newly created size object
* @static
*
* @example
* var maxSize = new Size(100, 100);
* var randomSize = Size.random();
* var size = maxSize * randomSize;
*
* @returns {Size} The newly created size object
* @static
*/
random: function() {
return Size.create(Math.random(), Math.random());
@ -398,14 +432,14 @@ var Size = this.Size = Base.extend({
* Returns a new size with rounded {@link #width} and {@link #height} values.
* The object itself is not modified!
*
* @name Size#round
* @function
* @return {Size}
*
* @example
* var size = new Size(10.2, 10.9);
* var roundSize = size.round();
* console.log(roundSize); // { x: 10.0, y: 11.0 }
*
* @name Size#round
* @function
* @return {Size}
*/
/**
@ -413,14 +447,14 @@ var Size = this.Size = Base.extend({
* specified {@link #width} and {@link #height} values. The object itself is not
* modified!
*
* @name Size#ceil
* @function
* @return {Size}
*
* @example
* var size = new Size(10.2, 10.9);
* var ceilSize = size.ceil();
* console.log(ceilSize); // { x: 11.0, y: 11.0 }
*
* @name Size#ceil
* @function
* @return {Size}
*/
/**
@ -428,28 +462,28 @@ var Size = this.Size = Base.extend({
* specified {@link #width} and {@link #height} values. The object itself is not
* modified!
*
* @name Size#floor
* @function
* @return {Size}
*
* @example
* var size = new Size(10.2, 10.9);
* var floorSize = size.floor();
* console.log(floorSize); // { x: 10.0, y: 10.0 }
*
* @name Size#floor
* @function
* @return {Size}
*/
/**
* Returns a new size with the absolute values of the specified {@link #width}
* and {@link #height} values. The object itself is not modified!
*
* @name Size#abs
* @function
* @return {Size}
*
* @example
* var size = new Size(-5, 10);
* var absSize = size.abs();
* console.log(absSize); // { x: 5.0, y: 10.0 }
*
* @name Size#abs
* @function
* @return {Size}
*/
return Base.each(['round', 'ceil', 'floor', 'abs'], function(name) {

2
src/color/Color.js
View file

@ -292,7 +292,7 @@ var Color = this.Color = Base.extend(new function() {
* console.log(color.type); // 'rgb'
* </code>
*
* @type String
* @type String('rgb', 'hsb', 'gray')
* @bean
*/
getType: function() {

2
src/color/Gradient.js
View file

@ -72,7 +72,7 @@ var Gradient = this.Gradient = Base.extend({
* Checks whether the gradient is equal to the supplied gradient.
*
* @param {Gradient} gradient
* @return {boolean} {@true they are equal}
* @return {Boolean} {@true they are equal}
*/
equals: function(gradient) {
if (gradient.type != this.type)

38
src/item/Group.js
View file

@ -22,20 +22,34 @@ var Group = this.Group = Item.extend({
/**
* Creates a new Group item and places it at the top of the active layer.
*
* @example
* // Create an empty group:
* var group = new Group();
* // Append a path to the group:
* var line = new Path.Line(new Point(10, 10), new Point(50, 50));
* group.appendTop(line);
*
* // Create a group containing a path:
* var circle = new Path.Circle(new Point(10, 10), 100);
* var circleGroup = new Group([circle]);
*
* @param {Array} [children] An optional array of children that will be
* added to the newly created group.
*
* @example
* // Create an empty group and append a path to the top of its children
* // array:
*
* // Create an empty group:
* var group = new Group();
*
* var path = new Path([new Point(10, 10), new Point(50, 50)]);
* path.strokeColor = 'black';
*
* // Append the path to the group:
* group.appendTop(path);
*
* // Set the stroke color of all items in the group:
* circleGroup.strokeColor = 'black';
*
* @example
* // Create a group containing two paths:
* var circle = new Path.Circle(new Point(30, 50), 10);
* var circle2 = new Path.Circle(new Point(50, 50), 10);
*
* var circleGroup = new Group([circle, circle2]);
* // Set the fill color of all items in the group:
* circleGroup.fillColor = 'black';
*
* @class A Group is a collection of items. When you transform a Group, its
* children are treated as a single unit without changing their relative
* positions.
@ -62,7 +76,7 @@ var Group = this.Group = Item.extend({
* When setting to true, the first child in the group is automatically
* defined as the clipping mask.
*
* @type boolean
* @type Boolean
* @bean
*/
isClipped: function() {

148
src/item/Item.js
View file

@ -64,13 +64,13 @@ var Item = this.Item = Base.extend({
* The name of the item. If the item has a name, it can be accessed by name
* through its parent's children list.
*
* @type String
* @bean
*
* @example
* var path = new Path();
* path.name = 'example';
* project.activeLayer.children['example'].remove();
*
* @type String
* @bean
*/
getName: function() {
return this._name;
@ -98,7 +98,12 @@ var Item = this.Item = Base.extend({
* The item's position within the project. This is the
* {@link Rectangle#center} of the {@link #bounds} rectangle.
*
* @type Point
* @bean
*
* @example
* // Changing the position of a path:
*
* // Create a circle at position { x: 10, y: 10 }
* var circle = new Path.Circle(new Point(10, 10), 10);
* circle.fillColor = 'red';
@ -111,6 +116,8 @@ var Item = this.Item = Base.extend({
* console.log(circle.position); // { x: 30, y: 30 }
*
* @example
* // Changing the x coordinate of an item's position:
*
* // Create a circle at position { x: 10, y: 10 }
* var circle = new Path.Circle(new Point(10, 10), 10);
* circle.fillColor = 'red';
@ -118,9 +125,6 @@ var Item = this.Item = Base.extend({
* // Move the circle 10 points to the right
* circle.position.x += 10;
* console.log(circle.position); // { x: 20, y: 10 }
*
* @type Point
* @bean
*/
getPosition: function() {
// Cache position value
@ -141,17 +145,19 @@ var Item = this.Item = Base.extend({
/**
* The path style of the item.
*
* @type PathStyle
* @bean
*
* @example
* // Applying several styles to an item in one go, by passing an object
* // to its style property:
* var circle = new Path.Circle(new Point(10, 10), 10);
* circle.style = {
* fillColor: new RGBColor(1, 0, 0),
* strokeColor: new RGBColor(0, 1, 0),
* strokeWidth: 5
* };
*
* @type PathStyle
* @bean
*/
getStyle: function() {
return this._style;
@ -170,15 +176,16 @@ var Item = this.Item = Base.extend({
* project. This can be useful for debugging, as it allows you to see the
* construction of paths, position of path curves, individual segment points
* and bounding boxes of symbol and raster items.
*
* @type Boolean
* @bean
*
* @example
* // Selecting an item:
* console.log(project.selectedItems.length); // 0
* var path = new Path.Circle(new Size(50, 50), 25);
* path.selected = true; // Select the path
* console.log(project.selectedItems.length) // 1
*
* @type boolean {@true the item is selected}
* @bean
* console.log(project.selectedItems.length); // 1
*/
isSelected: function() {
if (this._children) {
@ -215,7 +222,7 @@ var Item = this.Item = Base.extend({
/**
* Specifies whether the item is locked.
*
* @type boolean
* @type Boolean
* @default false
* @ignore
*/
@ -225,14 +232,14 @@ var Item = this.Item = Base.extend({
* Specifies whether the item is visible. When set to {@code false}, the
* item won't be drawn.
*
* @type Boolean
* @default true
*
* @example
* // Hiding an item:
* var path = new Path.Circle(new Point(50, 50), 20);
* path.fillColor = 'red';
* console.log(path.visible) // true
* path.visible = false; // Hides the path
*
* @type boolean {@true the item is visible}
* @default true
*/
visible: true,
@ -241,7 +248,7 @@ var Item = this.Item = Base.extend({
* paths, compound paths, and text frame objects, and only if the item is
* already contained within a clipping group.
*
* @type boolean
* @type Boolean
* @default false
* @bean
*/
@ -260,15 +267,14 @@ var Item = this.Item = Base.extend({
/**
* The blend mode of the item.
*
* @example
* var circle = new Path.Circle(new Point(50, 50), 10);
* circle.fillColor = 'red';
*
* // Change the blend mode of the path item:
* circle.blendMode = 'multiply';
*
* @type String('normal','screen','multiply','difference','src-in','add','overlay','hard-light','dodge','burn','darken','lighten','exclusion')
* @default 'normal'
*
* @example
* // Setting an item's blend mode to 'multiply':
* var circle = new Path.Circle(new Point(50, 50), 10);
* circle.fillColor = 'red';
* circle.blendMode = 'multiply';
*/
blendMode: 'normal',
@ -276,11 +282,11 @@ var Item = this.Item = Base.extend({
* The opacity of the item as a value between 0 and 1.
*
* @example
* // Making an item 50% transparent:
*
* // Create a circle at position { x: 50, y: 50 }
* var circle = new Path.Circle(new Point(50, 50), 20);
* circle.fillColor = 'red';
*
* // Change the opacity of the circle to 50%:
* circle.opacity = 0.5;
*
* @type Number
@ -320,6 +326,9 @@ var Item = this.Item = Base.extend({
/**
* The item that this item is contained within.
*
* @type Item
* @bean
*
* @example
* var path = new Path();
* // New items are placed in the active layer:
@ -329,9 +338,6 @@ var Item = this.Item = Base.extend({
* group.appendTop(path);
* // Now the parent of the path has become the group:
* console.log(path.parent == group); // true
*
* @type Item
* @bean
*/
getParent: function() {
return this._parent;
@ -340,6 +346,9 @@ var Item = this.Item = Base.extend({
/**
* The children items contained within this item. Items that define a
* {@link #name} can also be accessed by name.
*
* @type Item[]
* @bean
*
* @example
* var path = new Path();
@ -352,9 +361,6 @@ var Item = this.Item = Base.extend({
* path.name = 'example';
* // Now the path can also be accessed by name:
* console.log(group.children['example'] == path); // true
*
* @type Item[]
* @bean
*/
getChildren: function() {
return this._children;
@ -455,7 +461,7 @@ var Item = this.Item = Base.extend({
* Removes the item from the project. If the item has children, they are also
* removed.
*
* @return {boolean} {@true the item was removed}
* @return {Boolean} {@true the item was removed}
*/
remove: function() {
if (this.isSelected())
@ -466,7 +472,7 @@ var Item = this.Item = Base.extend({
/**
* Removes all of the item's children (if any).
*
* @return {boolean} {@true removing was successful}
* @return {Boolean} {@true removing was successful}
*/
removeChildren: function() {
var removed = false;
@ -535,7 +541,7 @@ var Item = this.Item = Base.extend({
/**
* Reverses the order of this item's children
*
* @return {boolean} {@true the children were removed}
* @return {Boolean} {@true the children were removed}
*/
reverseChildren: function() {
if (this._children) {
@ -575,7 +581,7 @@ var Item = this.Item = Base.extend({
* {@grouptitle Tests}
* Checks if the item contains any children items.
*
* @return {boolean} {@true it has one or more children}
* @return {Boolean} {@true it has one or more children}
*/
hasChildren: function() {
return this._children && this._children.length > 0;
@ -586,7 +592,7 @@ var Item = this.Item = Base.extend({
/**
* Checks whether the item is editable.
*
* @return {boolean} {@true when neither the item, nor its parents are
* @return {Boolean} {@true when neither the item, nor its parents are
* locked or hidden}
* @ignore
*/
@ -603,7 +609,7 @@ var Item = this.Item = Base.extend({
/**
* Checks whether the item is valid, i.e. it hasn't been removed.
*
* @return {boolean} {@true the item is valid}
* @return {Boolean} {@true the item is valid}
*/
// TODO: isValid / checkValid
@ -638,7 +644,7 @@ var Item = this.Item = Base.extend({
* of the project.
*
* @param {Item} item The item to check against
* @return {boolean} {@true if it is above the specified item}
* @return {Boolean} {@true if it is above the specified item}
*/
isAbove: function(item) {
return this._getOrder(item) == -1;
@ -649,7 +655,7 @@ var Item = this.Item = Base.extend({
* the project.
*
* @param {Item} item The item to check against
* @return {boolean} {@true if it is below the specified item}
* @return {Boolean} {@true if it is below the specified item}
*/
isBelow: function(item) {
return this._getOrder(item) == 1;
@ -660,7 +666,7 @@ var Item = this.Item = Base.extend({
* Checks whether the specified item is the parent of the item.
*
* @param {Item} item The item to check against
* @return {boolean} {@true if it is the parent of the item}
* @return {Boolean} {@true if it is the parent of the item}
*/
isParent: function(item) {
return this._parent == item;
@ -670,7 +676,7 @@ var Item = this.Item = Base.extend({
* Checks whether the specified item is a child of the item.
*
* @param {Item} item The item to check against
* @return {boolean} {@true it is a child of the item}
* @return {Boolean} {@true it is a child of the item}
*/
isChild: function(item) {
return item && item._parent == this;
@ -680,7 +686,7 @@ var Item = this.Item = Base.extend({
* Checks if the item is contained within the specified item.
*
* @param {Item} item The item to check against
* @return {boolean} {@true if it is inside the specified item}
* @return {Boolean} {@true if it is inside the specified item}
*/
// TODO: Consider naming this isInside?
isDescendant: function(item) {
@ -696,7 +702,7 @@ var Item = this.Item = Base.extend({
* Checks if the item is an ancestor of the specified item.
*
* @param {Item} item the item to check against
* @return {boolean} {@true if the item is an ancestor of the specified
* @return {Boolean} {@true if the item is an ancestor of the specified
* item}
*/
// TODO: Consider naming this contains?
@ -708,7 +714,7 @@ var Item = this.Item = Base.extend({
* Checks whether the item is grouped with the specified item.
*
* @param {Item} item
* @return {boolean} {@true if the items are grouped together}
* @return {Boolean} {@true if the items are grouped together}
*/
isGroupedWith: function(item) {
var parent = this._parent;
@ -811,7 +817,7 @@ var Item = this.Item = Base.extend({
* var circle = new Path.Circle(new Point(50, 50), 10);
*
* // Set the stroke color of the circle to RGB red:
* circle.strokeColor = new RGB(1, 0, 0);
* circle.strokeColor = new RGBColor(1, 0, 0);
*
* @property
* @name Item#strokeColor
@ -892,18 +898,20 @@ var Item = this.Item = Base.extend({
/**
* {@grouptitle Fill Style}
*
* The fill color.
* The fill color of the item.
*
* @property
* @name Item#fillColor
* @type RGBColor|HSBColor|GrayColor
*
* @example
* // Setting the fill color of a path to red:
*
* // Create a circle shaped path at { x: 50, y: 50 } with a radius of 10:
* var circle = new Path.Circle(new Point(50, 50), 10);
*
* // Set the fill color of the circle to RGB red:
* circle.fillColor = new RGBColor(1, 0, 0, );
*
* @property
* @name Item#fillColor
* @type RGBColor|HSBColor|GrayColor
*/
// DOCS: document the different arguments that this function can receive.
@ -913,35 +921,46 @@ var Item = this.Item = Base.extend({
* Scales the item by the given value from its center point, or optionally
* by a supplied point.
*
* @name Item#scale
* @function
* @param {Number} scale the scale factor
* @param {Point} [center=the center point of the item]
*
* @example
* // Scaling an item from its center point:
*
* // Create a circle at position { x: 10, y: 10 }
* var circle = new Path.Circle(new Point(10, 10), 10);
* console.log(circle.bounds.width); // 20
*
* // Scale the path by 200% around its center point
* // Scale the path by 200% from its center point
* circle.scale(2);
*
* console.log(circle.bounds.width); // 40
*
* @example
* // Scaling an item from a specific point:
*
* // Create a circle at position { x: 10, y: 10 }
* var circle = new Path.Circle(new Point(10, 10), 10);
*
* // Scale the path 200% from its bottom left corner
* circle.scale(2, circle.bounds.bottomLeft);
*
* @name Item#scale
* @function
* @param {Number} scale the scale factor
* @param {Point} [center=the center point of the item]
*/
/**
* Scales the item by the given values from its center point, or optionally
* by a supplied point.
*
* @param {Number} sx the horizontal scale factor
* @param {Number} sy the vertical scale factor
* @param {Point} [center=the center point of the item]
*
* @example
* // Scaling an item horizontally by 200%:
*
* // Create a circle at position { x: 10, y: 10 }
* var circle = new Path.Circle(new Point(10, 10), 10);
* circle.fillColor = 'black';
* console.log(circle.bounds.width); // 20
*
* // Scale the path horizontally by 200%
@ -950,15 +969,14 @@ var Item = this.Item = Base.extend({
* console.log(circle.bounds.width); // 40
*
* @example
* // Scaling an item horizontally by 200% from its bottom left corner:
*
* // Create a circle at position { x: 10, y: 10 }
* var circle = new Path.Circle(new Point(10, 10), 10);
* circle.fillColor = 'black';
*
* // Scale the path 200% horizontally from its bottom left corner
* circle.scale(1, 2, circle.bounds.bottomLeft);
*
* @param {Number} sx the horizontal scale factor
* @param {Number} sy the vertical scale factor
* @param {Point} [center=the center point of the item]
*/
scale: function(sx, sy /* | scale */, center) {
// See Matrix#scale for explanation of this:
@ -1209,7 +1227,7 @@ var Item = this.Item = Base.extend({
*
* @function
* @param {Item} item The item above which it should be moved
* @return {boolean} {@true it was moved}
* @return {Boolean} {@true it was moved}
*/
moveAbove: move(true),
@ -1218,7 +1236,7 @@ var Item = this.Item = Base.extend({
*
* @function
* @param {Item} item the item below which it should be moved
* @return {boolean} {@true it was moved}
* @return {Boolean} {@true it was moved}
*/
moveBelow: move(false)
};

7
src/item/Layer.js
View file

@ -25,13 +25,12 @@ var Layer = this.Layer = Group.extend({
* {@link Project#layers} array. The newly created layer will be activated,
* so all newly created items will be placed within it.
*
* @example
* var layer = new Layer();
* layer.name = 'the new layer';
*
* @param {Array} [children] An optional array of items that will be
* added to the newly created layer.
*
* @example
* var layer = new Layer();
*
* @class The Layer item represents a layer in a Paper.js project.
*
* The layer which is currently active can be accessed through

72
src/item/PathStyle.js
View file

@ -58,11 +58,11 @@ var PathStyle = this.PathStyle = Base.extend(new function() {
* <pre>
* var circleStyle = {
* fillColor: new RGBColor(1, 0, 0),
* strokeColor: new GrayColor(1),
* strokeColor: 'black',
* strokeWidth: 5
* };
*
* var path = new Path.Circle(new Point(50, 50), 50);
* var path = new Path.Circle(new Point(50, 50), 30);
* path.style = circleStyle;
* </pre>
*/
@ -157,46 +157,57 @@ var PathStyle = this.PathStyle = Base.extend(new function() {
*
* The color of the stroke.
*
* @example
* // Create a circle shaped path at { x: 50, y: 50 } with a radius of 10:
* var circle = new Path.Circle(new Point(50, 50), 10);
*
* // Set the stroke color of the circle to RGB red:
* circle.strokeColor = new RGB(1, 0, 0);
*
* @property
* @name PathStyle#strokeColor
* @type RGBColor|HSBColor|GrayColor
*
* @example
* // Setting an item's stroke color:
*
* // Create a circle shaped path at { x: 50, y: 50 }
* // with a radius of 10:
* var circle = new Path.Circle(new Point(50, 50), 10);
*
* // Set its stroke color to RGB red:
* circle.strokeColor = new RGBColor(1, 0, 0);
*/
/**
* The width of the stroke.
*
* @example
* // Create a circle shaped path at { x: 50, y: 50 } with a radius of 10:
* var circle = new Path.Circle(new Point(50, 50), 10);
*
* // Set the stroke width of the circle to 3pt:
* circle.strokeWidth = 3;
*
* @property
* @name PathStyle#strokeWidth
* @default 1
* @type Number
*
* @example
* // Setting an item's stroke width:
*
* // Create a circle shaped path at { x: 50, y: 50 }
* // with a radius of 10:
* var circle = new Path.Circle(new Point(50, 50), 10);
*
* // Set its stroke width to 3pt:
* circle.strokeWidth = 3;
*/
/**
* The cap of the stroke.
*
* @property
* @name PathStyle#strokeCap
* @default 'butt'
* @type String('round', 'square', 'butt')
*
* @example
* // Setting an item's stroke color:
*
* // Create a line from { x: 0, y: 50 } to { x: 50, y: 50 };
* var line = new Path.Line(new Point(0, 50), new Point(50, 50));
* line.strokeColor = 'black';
*
* // Set the stroke cap of the line to be round:
* line.strokeCap = 'round';
*
* @property
* @name PathStyle#strokeCap
* @type String('round', 'square', 'butt')
*/
/**
@ -204,6 +215,7 @@ var PathStyle = this.PathStyle = Base.extend(new function() {
*
* @property
* @name PathStyle#strokeJoin
* @default 'miter'
* @type String ('miter', 'round', 'bevel')
*/
@ -212,6 +224,7 @@ var PathStyle = this.PathStyle = Base.extend(new function() {
// *
// * @property
// * @name PathStyle#dashOffset
// * @default 0
// * @type Number
// */
@ -229,6 +242,7 @@ var PathStyle = this.PathStyle = Base.extend(new function() {
// *
// * @property
// * @name PathStyle#dashArray
// * @default []
// * @type Array
// */
@ -237,6 +251,7 @@ var PathStyle = this.PathStyle = Base.extend(new function() {
*
* @property
* @name PathStyle#miterLimit
* @default 10
* @type Number
*/
@ -245,14 +260,17 @@ var PathStyle = this.PathStyle = Base.extend(new function() {
*
* The fill color.
*
* @example
* // Create a circle shaped path at { x: 50, y: 50 } with a radius of 10:
* var circle = new Path.Circle(new Point(50, 50), 10);
*
* // Set the fill color of the circle to RGB red:
* circle.fillColor = new RGBColor(1, 0, 0, );
*
* @property
* @name PathStyle#fillColor
* @type RGBColor|HSBColor|GrayColor
*
* @example
* // Setting the fill color of an item:
*
* // Create a circle shaped path at { x: 50, y: 50 }
* // with a radius of 10:
* var circle = new Path.Circle(new Point(50, 50), 10);
*
* // Set its fill color to RGB red:
* circle.fillColor = new RGBColor(1, 0, 0, );
*/

17
src/item/PlacedSymbol.js
View file

@ -22,7 +22,13 @@ var PlacedSymbol = this.PlacedSymbol = Item.extend({
/**
* Creates a new PlacedSymbol Item.
*
* @param {Symbol} symbol the symbol to place
* @param {Point|Matrix} matrixOrOffset the center point of the placed
* symbol or a {@link Matrix} transformation to transform the placed symbol
* with.
*
* @example
* // Placing 100 instances of a symbol:
* var path = new Path.Star(new Point(0, 0), 6, 5, 13);
* path.style = {
* fillColor: 'white',
@ -49,13 +55,8 @@ var PlacedSymbol = this.PlacedSymbol = Item.extend({
* instance.scale(0.25 + Math.random() * 0.75);
* }
*
* @param {Symbol} symbol the symbol to place
* @param {Point|Matrix} matrixOrOffset the center point of the placed
* symbol or a {@link Matrix} transformation to transform the placed symbol
* with.
*
* @class A PlacedSymbol represents a symbol which has been placed in a
* Paper.js project.
* @class A PlacedSymbol represents an instance of a symbol which has been
* placed in a Paper.js project.
*
* @extends Item
* @constructs PlacedSymbol
@ -71,7 +72,7 @@ var PlacedSymbol = this.PlacedSymbol = Item.extend({
},
/**
* The symbol contained within the placed symbol.
* The symbol that the placed symbol refers to:
*
* @name PlacedSymbol#symbol
* @type Symbol

12
src/path/CompoundPath.js
View file

@ -22,6 +22,16 @@ var CompoundPath = this.CompoundPath = PathItem.extend({
*
* @constructs CompoundPath
* @param {Array} [paths] the paths to place within the compound path.
*
* @example
* // Create a donut shaped compound path:
* var circle = new Path.Circle(new Point(50, 50), 30);
* var innerCircle = new Path.Circle(new Point(50, 50), 10);
* var compoundPath = new CompoundPath([circle, innerCircle]);
* compoundPath.fillColor = 'red';
*
* // Move the inner circle 5pt to the right:
* compoundPath.children[1].position.x += 5;
*
* @class A compound path contains two or more paths, holes are drawn
* where the paths overlap. All the paths in a compound path take on the
@ -186,7 +196,7 @@ var CompoundPath = this.CompoundPath = PathItem.extend({
* @name CompoundPath#arcTo
* @function
* @param {Point} to
* @param {boolean} [clockwise=true]
* @param {Boolean} [clockwise=true]
*/
// DOCS: document CompoundPath#lineBy

10
src/path/Curve.js
View file

@ -182,7 +182,7 @@ var Curve = this.Curve = Base.extend({
/**
* Specifies whether the handles of the curve are selected.
*
* @type boolean
* @type Boolean
* @bean
*/
isSelected: function() {
@ -234,19 +234,19 @@ var Curve = this.Curve = Base.extend({
* Checks if this curve is linear, meaning it does not define any curve
* handle.
* @return {boolean} {@true the curve is linear}
* @return {Boolean} {@true the curve is linear}
*/
isLinear: function() {
return this._segment1._handleOut.isZero()
&& this._segment2._handleIn.isZero();
},
// PORT: Add support for start parameter to Scriptographer
// PORT: Add support for start parameter to Sg
// DOCS: document Curve#getParameter(length, start)
/**
* @param {Number} length
* @param {Number} [start]
* @return {boolean} {@true the curve is linear}
* @return {Boolean} {@true the curve is linear}
*/
getParameter: function(length, start) {
var args = this.getCurveValues();
@ -328,7 +328,7 @@ var Curve = this.Curve = Base.extend({
x, y;
// Handle special case at beginning / end of curve
// PORT: Change in Scriptographer too, so 0.000000000001 won't be
// PORT: Change in Sg too, so 0.000000000001 won't be
// required anymore
if (t == 0 || t == 1) {
var point;

2
src/path/Path.Constructors.js
View file

@ -157,7 +157,7 @@ Path.inject({ statics: new function() {
* Creates an oval shaped Path Item.
*
* @param {Rectangle} rect
* @param {boolean} [circumscribed=false] if this is set to true the
* @param {Boolean} [circumscribed=false] if this is set to true the
* oval shaped path will be created so the rectangle fits into
* it. If it's set to false the oval path will fit within the
* rectangle.

48
src/path/Path.js
View file

@ -22,20 +22,21 @@ var Path = this.Path = PathItem.extend({
/**
* Creates a new Path item and places it at the top of the active layer.
*
* @example
* var firstSegment = new Segment(30, 30);
* var secondSegment = new Segment(100, 100);
* var path = new Path([firstSegment, secondSegment]);
* path.strokeColor = 'black';
*
* @example
* var path = new Path();
* path.strokeColor = 'black';
* path.moveTo(30, 30);
* path.lineTo(100, 100);
*
* @param {Segment[]} [segments] An optional array of segments (or points to be
* converted to segments) that will be added to the path.
*
* @example
* // Create an empty path and add segments to it:
* var path = new Path();
* path.strokeColor = 'black';
* path.add(new Point(30, 30));
* path.add(new Point(100, 100));
*
* @example
* // Create a path with two segments:
* var segments = [new Point(30, 30), new Point(100, 100)];
* var path = new Path(segments);
* path.strokeColor = 'black';
*
* @class The Path item represents a path in a Paper.js project.
* @extends PathItem
@ -326,15 +327,16 @@ var Path = this.Path = PathItem.extend({
* Adds an array of segments (or types that can be converted to segments)
* to the end of the {@link #segments} array.
*
* @param {Segment[]} segments
* @return {Segment[]} an array of the added segments. These segments are
* not necessarily the same objects, e.g. if the segment to be added already
* belongs to another path.
*
* @example
* var path = new Path();
* path.strokeColor = 'black';
* var points = [new Point(10, 10), new Point(50, 50)];
* path.addSegments(points);
* @param {Segment[]} segments
* @return {Segment[]} an array of the added segments. These segments are
* not necessarily the same objects, e.g. if the segment to be added already
* belongs to another path.
*/
addSegments: function(segments) {
return this._add(Segment.readAll(segments));
@ -436,7 +438,7 @@ var Path = this.Path = PathItem.extend({
/**
* Specifies whether all segments of the path are selected.
*
* @type boolean
* @type Boolean
* @bean
*/
isFullySelected: function() {
@ -455,7 +457,7 @@ var Path = this.Path = PathItem.extend({
/**
* Specifies whether the path is oriented clock-wise.
*
* @type boolean
* @type Boolean
* @bean
*/
isClockwise: function() {
@ -596,7 +598,7 @@ var Path = this.Path = PathItem.extend({
// DOCS: document Path#getLocationAt
/**
* @param {Number} offset
* @param {boolean} [isParameter=false]
* @param {Boolean} [isParameter=false]
*/
getLocationAt: function(offset, isParameter) {
var curves = this.getCurves(),
@ -629,7 +631,7 @@ var Path = this.Path = PathItem.extend({
* Get the point of the path at the given offset.
*
* @param {Number} offset
* @param {boolean} [isParameter=false]
* @param {Boolean} [isParameter=false]
* @return {Point} the point at the given offset
*/
getPointAt: function(offset, isParameter) {
@ -642,7 +644,7 @@ var Path = this.Path = PathItem.extend({
* point.
*
* @param {Number} offset
* @param {boolean} [isParameter=false]
* @param {Boolean} [isParameter=false]
* @return {Point} the tangent vector at the given offset
*/
getTangentAt: function(offset, isParameter) {
@ -654,7 +656,7 @@ var Path = this.Path = PathItem.extend({
* Get the normal to the path at the given offset as a vector point.
*
* @param {Number} offset
* @param {boolean} [isParameter=false]
* @param {Boolean} [isParameter=false]
* @return {Point} the normal vector at the given offset
*/
getNormalAt: function(offset, isParameter) {
@ -1040,7 +1042,7 @@ var Path = this.Path = PathItem.extend({
// DOCS: document Path#arcTo
/**
* @param {Point} to
* @param {boolean} [clockwise=true]
* @param {Boolean} [clockwise=true]
*/
arcTo: function(to, clockwise) {
// Get the start point:

155
src/path/Segment.js
View file

@ -21,6 +21,16 @@ var Segment = this.Segment = Base.extend({
/**
* Creates a new Segment object.
*
* @name Segment
* @constructor
* @param {Point} [point={x: 0, y: 0}] the anchor point of the segment
* @param {Point} [handleIn={x: 0, y: 0}] the handle point relative to the
* anchor point of the segment that describes the in tangent of the
* segment.
* @param {Point} [handleOut={x: 0, y: 0}] the handle point relative to the
* anchor point of the segment that describes the out tangent of the
* segment.
*
* @example
* var handleIn = new Point(-40, -50);
* var handleOut = new Point(40, 50);
@ -33,16 +43,7 @@ var Segment = this.Segment = Base.extend({
*
* var path = new Path();
* path.segments = [firstSegment, secondSegment];
*
* @param {Point} [point={x: 0, y: 0}] the anchor point of the segment
* @param {Point} [handleIn={x: 0, y: 0}] the handle point relative to the
* anchor point of the segment that describes the in tangent of the
* segment.
* @param {Point} [handleOut={x: 0, y: 0}] the handle point relative to the
* anchor point of the segment that describes the out tangent of the
* segment.
* @name Segment
* @constructor
* path.strokeColor = 'black';
*
* @class The Segment object represents a part of a path which is
* described by the {@link Path#segments} array. Every segment of a
@ -170,6 +171,73 @@ var Segment = this.Segment = Base.extend({
? null : this._handleOut;
},
_isSelected: function(point) {
var state = this._selectionState;
return point == this._point ? !!(state & SelectionState.POINT)
: point == this._handleIn ? !!(state & SelectionState.HANDLE_IN)
: point == this._handleOut ? !!(state & SelectionState.HANDLE_OUT)
: false;
},
_setSelected: function(point, selected) {
var path = this._path,
selected = !!selected, // convert to boolean
state = this._selectionState,
wasSelected = !!state,
// For performance reasons use array indices to access the various
// selection states: 0 = point, 1 = handleIn, 2 = handleOut
selection = [
!!(state & SelectionState.POINT),
!!(state & SelectionState.HANDLE_IN),
!!(state & SelectionState.HANDLE_OUT)
];
if (point == this._point) {
if (selected) {
// We're selecting point, deselect the handles
selection[1] = selection[2] = false;
} else {
var previous = this.getPrevious(),
next = this.getNext();
// When deselecting a point, the handles get selected instead
// depending on the selection state of their neighbors.
selection[1] = previous && (previous._point.isSelected()
|| previous._handleOut.isSelected());
selection[2] = next && (next._point.isSelected()
|| next._handleIn.isSelected());
}
selection[0] = selected;
} else {
var index = point == this._handleIn ? 1 : 2;
if (selection[index] != selected) {
// When selecting handles, the point get deselected.
if (selected)
selection[0] = false;
selection[index] = selected;
}
}
this._selectionState = (selection[0] ? SelectionState.POINT : 0)
| (selection[1] ? SelectionState.HANDLE_IN : 0)
| (selection[2] ? SelectionState.HANDLE_OUT : 0);
// If the selection state of the segment has changed, we need to let
// it's path know and possibly add or remove it from
// project._selectedItems
if (path && wasSelected != !!this._selectionState)
path._updateSelection(this);
},
/**
* Specifies whether the {@link #point} of the segment is selected.
* @type Boolean
* @bean
*/
isSelected: function() {
return this._isSelected(this._point);
},
setSelected: function(selected) {
this._setSelected(this._point, selected);
},
/**
* {@grouptitle Hierarchy}
*
@ -240,73 +308,6 @@ var Segment = this.Segment = Base.extend({
|| this._path._closed && segments[segments.length - 1]) || null;
},
_isSelected: function(point) {
var state = this._selectionState;
return point == this._point ? !!(state & SelectionState.POINT)
: point == this._handleIn ? !!(state & SelectionState.HANDLE_IN)
: point == this._handleOut ? !!(state & SelectionState.HANDLE_OUT)
: false;
},
_setSelected: function(point, selected) {
var path = this._path,
selected = !!selected, // convert to boolean
state = this._selectionState,
wasSelected = !!state,
// For performance reasons use array indices to access the various
// selection states: 0 = point, 1 = handleIn, 2 = handleOut
selection = [
!!(state & SelectionState.POINT),
!!(state & SelectionState.HANDLE_IN),
!!(state & SelectionState.HANDLE_OUT)
];
if (point == this._point) {
if (selected) {
// We're selecting point, deselect the handles
selection[1] = selection[2] = false;
} else {
var previous = this.getPrevious(),
next = this.getNext();
// When deselecting a point, the handles get selected instead
// depending on the selection state of their neighbors.
selection[1] = previous && (previous._point.isSelected()
|| previous._handleOut.isSelected());
selection[2] = next && (next._point.isSelected()
|| next._handleIn.isSelected());
}
selection[0] = selected;
} else {
var index = point == this._handleIn ? 1 : 2;
if (selection[index] != selected) {
// When selecting handles, the point get deselected.
if (selected)
selection[0] = false;
selection[index] = selected;
}
}
this._selectionState = (selection[0] ? SelectionState.POINT : 0)
| (selection[1] ? SelectionState.HANDLE_IN : 0)
| (selection[2] ? SelectionState.HANDLE_OUT : 0);
// If the selection state of the segment has changed, we need to let
// it's path know and possibly add or remove it from
// project._selectedItems
if (path && wasSelected != !!this._selectionState)
path._updateSelection(this);
},
/**
* Specifies whether the {@link #point} of the segment is selected.
* @type Boolean
* @bean
*/
isSelected: function() {
return this._isSelected(this._point);
},
setSelected: function(selected) {
this._setSelected(this._point, selected);
},
/**
* Returns the reversed the segment, without modifying the segment itself.
* @return {Segment} the reversed segment

19
src/project/Project.js
View file

@ -65,6 +65,25 @@ var Project = this.Project = Base.extend({
*
* @type PathStyle
* @bean
*
* @example
* project.currentStyle = {
* fillColor: 'red',
* strokeColor: 'black',
* strokeWidth: 5
* }
*
* // The following path will take over all style properties of
* // the current style:
* var path = new Path.Circle(new Point(50, 50), 30);
* console.log(path.strokeWidth); // 5
*
* @example
* project.currentStyle.fillColor = 'red';
*
* // The following path will take over the fill color we just set:
* var path = new Path.Circle(new Point(50, 50), 30);
* console.log(path.fillColor); // RGBColor(1, 0, 0)
*/
getCurrentStyle: function() {
return this._currentStyle;

22
src/project/Symbol.js
View file

@ -28,15 +28,7 @@ var Symbol = this.Symbol = Base.extend({
* @name Symbol
* @constructor
*
* @class Symbols allow you to place multiple instances of an item in your
* project. This can save memory, since all instances of a symbol
* simply refer to the original item and it can speed up moving
* around complex objects, since internal properties such as segment
* lists and gradient positions don't need to be updated with every
* transformation.
*
* Sample code:
* <pre>
* @example
* var circlePath = new Path.Circle(new Point(100, 100), 50);
* circlePath.fillColor = 'red';
*
@ -45,10 +37,18 @@ var Symbol = this.Symbol = Base.extend({
* // The original item is still contained in the document:
* circlePath.remove();
*
* // To place instances of the symbol in the document:
* // Place an instance of the symbol in the document:
* var placedCircle = new PlacedSymbol(circleSymbol);
*
* // Move the placed symbol to {x: 150, y: 150}:
* placedCircle.position = new Point(150, 150);
* </pre>
*
* @class Symbols allow you to place multiple instances of an item in your
* project. This can save memory, since all instances of a symbol
* simply refer to the original item and it can speed up moving
* around complex objects, since internal properties such as segment
* lists and gradient positions don't need to be updated with every
* transformation.
*/
initialize: function(item) {
this.project = paper.project;

12
src/text/CharacterStyle.js
View file

@ -30,13 +30,15 @@ var CharacterStyle = this.CharacterStyle = PathStyle.extend({
* @class The CharacterStyle object represents the character style of a text
* item ({@link TextItem#characterStyle})
*
* Sample code:
* <pre>
* Example:
* <code>
* var text = new PointText(new Point(50, 50));
* text.fillColor = 'black';
* text.content = 'Hello world.';
* text.characterStyle.fontSize = 50;
* </pre>
* text.characterStyle = {
* fontSize: 50,
* fillColor: 'black',
* };
* </code>
*
* @extends PathStyle
*/

15
src/text/PointText.js
View file

@ -23,21 +23,18 @@ var PointText = this.PointText = TextItem.extend({
* Creates a point text item
*
* @param {Point} point the position where the text will start
*
* @constructs PointText
*
* @example
* var text = new PointText(new Point(50, 100));
* text.paragraphStyle.justification = 'center';
* text.characterStyle.fillColor = 'black';
* text.content = 'The contents of the point text';
*
* @class A PointText item represents a piece of typography in your Paper.js
* project which starts from a certain point and extends by the amount of
* characters contained in it.
*
* Sample code:
* <pre>
* var text = new PointText(new Point(50, 100));
* text.paragraphStyle.justification = 'center';
* text.content = 'The contents of the point text';
* text.fillColor = 'black';
* </pre>
*
* @extends TextItem
* @extends Item
*/

105
src/tool/Tool.js
View file

@ -46,12 +46,13 @@ var Tool = this.Tool = Base.extend({
* function onMouseDown(event) {
* // Create a new path every time the mouse is clicked
* path = new Path();
* path.add(event.point);
* path.strokeColor = 'black';
* }
*
* function onMouseDrag(event) {
* // Add a point to the path every time the mouse is dragged
* path.lineTo(event.point);
* path.add(event.point);
* }
* </pre>
*/
@ -134,15 +135,18 @@ var Tool = this.Tool = Base.extend({
* function receives a {@link ToolEvent} object which contains information
* about the mouse event.
*
* @example
* function onMouseDown(event) {
* // the position of the mouse in project coordinates:
* console.log(event.point);
* }
*
* @name Tool#onMouseDown
* @property
* @type function
*
* @example
* // Creating circle shaped paths where the user presses the mouse button:
* function onMouseDown(event) {
* // Create a new circle shaped path with a radius of 10
* // at the position of the mouse (event.point):
* var path = new Path.Circle(event.point, 10);
* path.fillColor = 'black';
* }
*/
/**
@ -153,30 +157,44 @@ var Tool = this.Tool = Base.extend({
* This function can also be called periodically while the mouse doesn't
* move by setting the {@link #eventInterval}
*
* @example
* function onMouseDrag(event) {
* // the position of the mouse in project coordinates
* console.log(event.point);
* }
*
* @name Tool#onMouseDrag
* @property
* @type function
*
* @example
* // Draw a line by adding a segment to a path on every mouse drag event:
*
* // Create an empty path:
* var path = new Path();
* path.strokeColor = 'black';
*
* function onMouseDrag(event) {
* // Add a segment to the path at the position of the mouse:
* path.add(event.point);
* }
*/
/**
* The function to be called when the tool is selected and the mouse moves
* within the document. The function receives a {@link ToolEvent} object
* which contains information about the mouse event.
* The function to be called the mouse moves within the project view. The
* function receives a {@link ToolEvent} object which contains information
* about the mouse event.
*
* @example
* function onMouseMove(event) {
* // the position of the mouse in project coordinates
* console.log(event.point);
* }
* @name Tool#onMouseMove
* @property
* @type function
*
* @example
* // Moving a path to the position of the mouse:
*
* // Create a circle shaped path with a radius of 10 at {x: 0, y: 0}:
* var path = new Path.Circle([0, 0], 10);
* path.fillColor = 'black';
*
* function onMouseMove(event) {
* // Whenever the user moves the mouse, move the path
* // to that position:
* path.position = event.point;
* }
*/
/**
@ -184,14 +202,18 @@ var Tool = this.Tool = Base.extend({
* receives a {@link ToolEvent} object which contains information about the
* mouse event.
*
* @example
* function onMouseUp(event) {
* // the position of the mouse in project coordinates
* console.log(event.point);
* }
* @name Tool#onMouseUp
* @property
* @type function
*
* @example
* // Creating circle shaped paths where the user releases the mouse:
* function onMouseUp(event) {
* // Create a new circle shaped path with a radius of 10
* // at the position of the mouse (event.point):
* var path = new Path.Circle(event.point, 10);
* path.fillColor = 'black';
* }
*/
/**
@ -205,15 +227,26 @@ var Tool = this.Tool = Base.extend({
* window from scrolling, when you need the user to interact with arrow
* keys.
*
* @example
* function onKeyDown(event) {
* if(event.key == 'space') {
* console.log('The spacebar was pressed!');
* }
* }
* @name Tool#onKeyDown
* @property
* @type Function
*
* @example
* // Scaling a path whenever the user presses the space bar:
*
* // Create a circle shaped path:
* var path = new Path.Circle(new Point(50, 50), 30);
* path.fillColor = 'red';
*
* function onKeyDown(event) {
* if(event.key == 'space') {
* // Scale the path by 110%:
* path.scale(1.1);
*
* // Prevent the key event from bubbling
* return false;
* }
* }
*/
/**
@ -224,6 +257,10 @@ var Tool = this.Tool = Base.extend({
* prevented from bubbling up. This can be used for example to stop the
* window from scrolling, when you need the user to interact with arrow
* keys.
*
* @name Tool#onKeyUp
* @property
* @type Function
*
* @example
* function onKeyUp(event) {
@ -231,10 +268,6 @@ var Tool = this.Tool = Base.extend({
* console.log('The spacebar was released!');
* }
* }
*
* @name Tool#onKeyUp
* @property
* @type Function
*/
updateEvent: function(type, pt, minDistance, maxDistance, start,

30
src/ui/Key.js
View file

@ -14,6 +14,10 @@
* All rights reserved.
*/
/**
* @namespace
* @name Key
*/
var Key = this.Key = new function() {
// TODO: make sure the keys are called the same as in Scriptographer
// Missing: tab, cancel, clear, page-down, page-up, comma, minus, period,
@ -72,7 +76,7 @@ var Key = this.Key = new function() {
// Call the onKeyDown or onKeyUp handler if present
// When the handler function returns false, prevent the
// default behaviour of the key event:
// PORT: Add to Scriptographer
// PORT: Add to Sg
var keyEvent = new KeyEvent(down, key, character, event);
if (tool[handler](keyEvent) === false)
keyEvent.preventDefault();
@ -118,7 +122,7 @@ var Key = this.Key = new function() {
var code = event.which || event.keyCode,
key = keys[code], name;
if (key && modifiers[name = Base.camelize(key)] !== undefined) {
modifiers[name] = false
modifiers[name] = false;
} else if (charCodeMap[code] != null) {
handleKey(false, code, charCodeMap[code], event);
delete charCodeMap[code];
@ -127,8 +131,30 @@ var Key = this.Key = new function() {
});
return {
/** @lends Key */
modifiers: modifiers,
/**
* Checks whether the specified key is pressed.
*
* @param {String} key One of: 'backspace', 'enter', 'shift', 'control',
* 'option', 'pause', 'caps-lock', 'escape', 'space', 'end', 'home',
* 'left', 'up', 'right', 'down', 'delete', 'command'
* @return {Boolean} {@true if the key is pressed}
*
* @example
* // Whenever the user clicks, create a circle shaped path. If the
* // shift key is down, fill it with red, otherwise fill it with blue:
* function onMouseDown(event) {
* var path = new Path.Circle(event.point, 10);
* if(Key.isDown('shift')) {
* path.fillColor = 'red';
* } else {
* path.fillColor = 'blue';
* }
* }
*/
isDown: function(key) {
return !!keyMap[key];
}