diff --git a/src/basic/Line.js b/src/basic/Line.js
index 8047f615..341b7f7c 100644
--- a/src/basic/Line.js
+++ b/src/basic/Line.js
@@ -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
*/
/**
diff --git a/src/basic/Matrix.js b/src/basic/Matrix.js
index cee64fc9..b0d5aa95 100644
--- a/src/basic/Matrix.js
+++ b/src/basic/Matrix.js
@@ -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();
diff --git a/src/basic/Point.js b/src/basic/Point.js
index 8614595c..15c884b1 100644
--- a/src/basic/Point.js
+++ b/src/basic/Point.js
@@ -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) {
diff --git a/src/basic/Rectangle.js b/src/basic/Rectangle.js
index bbe43f49..edd3935d 100644
--- a/src/basic/Rectangle.js
+++ b/src/basic/Rectangle.js
@@ -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) {
diff --git a/src/basic/Size.js b/src/basic/Size.js
index 601ee142..32bb9945 100644
--- a/src/basic/Size.js
+++ b/src/basic/Size.js
@@ -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) {
diff --git a/src/color/Color.js b/src/color/Color.js
index e48157f8..d2e8496c 100644
--- a/src/color/Color.js
+++ b/src/color/Color.js
@@ -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() {
diff --git a/src/color/Gradient.js b/src/color/Gradient.js
index b3fdd9b0..639cdc3c 100644
--- a/src/color/Gradient.js
+++ b/src/color/Gradient.js
@@ -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)
diff --git a/src/item/Group.js b/src/item/Group.js
index 4c4ba2c0..78068db2 100644
--- a/src/item/Group.js
+++ b/src/item/Group.js
@@ -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() {
diff --git a/src/item/Item.js b/src/item/Item.js
index 7adf1455..96256d50 100644
--- a/src/item/Item.js
+++ b/src/item/Item.js
@@ -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)
};
diff --git a/src/item/Layer.js b/src/item/Layer.js
index 9c42e141..defffa9b 100644
--- a/src/item/Layer.js
+++ b/src/item/Layer.js
@@ -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
diff --git a/src/item/PathStyle.js b/src/item/PathStyle.js
index 0c56f564..75f1a36d 100644
--- a/src/item/PathStyle.js
+++ b/src/item/PathStyle.js
@@ -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, );
*/
\ No newline at end of file
diff --git a/src/item/PlacedSymbol.js b/src/item/PlacedSymbol.js
index 78500370..6fb5ca8a 100644
--- a/src/item/PlacedSymbol.js
+++ b/src/item/PlacedSymbol.js
@@ -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
diff --git a/src/path/CompoundPath.js b/src/path/CompoundPath.js
index 187d07c3..bca3b713 100644
--- a/src/path/CompoundPath.js
+++ b/src/path/CompoundPath.js
@@ -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
diff --git a/src/path/Curve.js b/src/path/Curve.js
index 7f90e81f..918cae88 100644
--- a/src/path/Curve.js
+++ b/src/path/Curve.js
@@ -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;
diff --git a/src/path/Path.Constructors.js b/src/path/Path.Constructors.js
index df03cc51..ab156975 100644
--- a/src/path/Path.Constructors.js
+++ b/src/path/Path.Constructors.js
@@ -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.
diff --git a/src/path/Path.js b/src/path/Path.js
index 1b1aec1b..16c40da6 100644
--- a/src/path/Path.js
+++ b/src/path/Path.js
@@ -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:
diff --git a/src/path/Segment.js b/src/path/Segment.js
index 2e2cdf0e..2625ecda 100644
--- a/src/path/Segment.js
+++ b/src/path/Segment.js
@@ -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
diff --git a/src/project/Project.js b/src/project/Project.js
index 78e44144..ca86e376 100644
--- a/src/project/Project.js
+++ b/src/project/Project.js
@@ -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;
diff --git a/src/project/Symbol.js b/src/project/Symbol.js
index bbf7c9ab..5ed4f5a4 100644
--- a/src/project/Symbol.js
+++ b/src/project/Symbol.js
@@ -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;
diff --git a/src/text/CharacterStyle.js b/src/text/CharacterStyle.js
index 27f589c7..fee5c19f 100644
--- a/src/text/CharacterStyle.js
+++ b/src/text/CharacterStyle.js
@@ -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
*/
diff --git a/src/text/PointText.js b/src/text/PointText.js
index c2d7e63b..535cb2e3 100644
--- a/src/text/PointText.js
+++ b/src/text/PointText.js
@@ -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
*/
diff --git a/src/tool/Tool.js b/src/tool/Tool.js
index a2466362..8b1d2058 100644
--- a/src/tool/Tool.js
+++ b/src/tool/Tool.js
@@ -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,
diff --git a/src/ui/Key.js b/src/ui/Key.js
index 909a25cf..fa0a645b 100644
--- a/src/ui/Key.js
+++ b/src/ui/Key.js
@@ -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];
}