Merge remote-tracking branch 'origin/master'

src/color/Color.js

@@ -531,6 +531,16 @@ var GrayColor = this.GrayColor = Color.extend(/** @scope GrayColor */{
 	 * 
 	 * @class A GrayColor object is used to represent any gray color value.
 	 * @extends Color
+	 * 
+	 * @example {@paperscript}
+	 * // Creating a GrayColor:
+	 * 
+	 * // Create a circle shaped path at {x: 80, y: 50}
+	 * // with a radius of 30:
+	 * var circle = new Path.Circle(new Point(80, 50), 30);
+	 *
+	 * // Create a GrayColor with 50% gray:
+	 * circle.fillColor = new GrayColor(0.5);
 	 */
 
 	_colorType: 'gray'
@@ -553,6 +563,16 @@ var RGBColor = this.RGBColor = Color.extend(/** @scope RGBColor */{
 	 * 
 	 * @class An RGBColor object is used to represent any RGB color value.
 	 * @extends Color
+	 * 
+	 * @example {@paperscript}
+	 * // Creating an RGBColor:
+	 * 
+	 * // Create a circle shaped path at {x: 80, y: 50}
+	 * // with a radius of 30:
+	 * var circle = new Path.Circle(new Point(80, 50), 30);
+	 *
+	 * // 100% red, 0% blue, 50% blue:
+	 * circle.fillColor = new RGBColor(1, 0, 0.5);
 	 */
 
 	_colorType: 'rgb'
@@ -575,6 +595,17 @@ var HSBColor = this.HSBColor = Color.extend(/** @scope HSBColor */{
 	 * 
 	 * @class An HSBColor object is used to represent any HSB color value.
 	 * @extends Color
+	 *
+	 * @example {@paperscript}
+	 * // Creating an HSBColor:
+	 * 
+	 * // Create a circle shaped path at {x: 80, y: 50}
+	 * // with a radius of 30:
+	 * var circle = new Path.Circle(new Point(80, 50), 30);
+	 *
+	 * // Create an HSBColor with a hue of 90 degrees, a saturation
+	 * // 100% and a brightness of 100%:
+	 * circle.fillColor = new HSBColor(90, 1, 1);
 	 */
 
 	_colorType: 'hsb'

src/item/Item.js

@@ -297,7 +297,10 @@ var Item = this.Item = Base.extend({
 	/**
 	 * The blend mode of the item.
 	 * 
-	 * @type String('normal', 'multiply', 'screen', 'overlay', 'soft-light', 'hard-light', 'color-dodge', 'color-burn', 'darken', 'lighten', 'difference', 'exclusion', 'hue', 'saturation', 'luminosity', 'color', 'add', 'subtract', 'average', 'pin-light', 'negation')
+	 * @type String('normal', 'multiply', 'screen', 'overlay', 'soft-light',
+	 * 'hard-light', 'color-dodge', 'color-burn', 'darken', 'lighten',
+	 * 'difference', 'exclusion', 'hue', 'saturation', 'luminosity', 'color',
+	 * 'add', 'subtract', 'average', 'pin-light', 'negation')
 	 * @default 'normal'
 	 * 
 	 * @example {@paperscript}
@@ -591,7 +594,7 @@ var Item = this.Item = Base.extend({
 	 * for (var i = 0; i < 20; i++) {
 	 * 	var copy = circle.clone();
 	 * 
-	 * 	// Move the copies horizontally, so we can see them:
+	 * 	// Distribute the copies horizontally, so we can see them:
 	 * 	copy.position.x += i * copy.bounds.width;
 	 * }
 	 */

src/path/Path.js

@@ -693,6 +693,42 @@ var Path = this.Path = PathItem.extend({
 		this.setSegments(segments);
 	},
 
+	/**
+	 * @param {Number} [tolerance=2.5]
+	 * 
+	 * @example {@paperscript height=300}
+	 * // Click and drag below to draw to draw a line, when you release the
+	 * // mouse, the is made smooth using path.pointsToCurves():
+	 * 
+	 * var path;
+	 * function onMouseDown(event) {
+	 * 	// If we already made a path before, deselect it:
+	 * 	if (path) {
+	 * 		path.selected = false;
+	 * 	}
+	 * 	
+	 * 	// Create a new path and add the position of the mouse
+	 * 	// as its first segment. Select it, so we can see the
+	 * 	// segment points:
+	 * 	path = new Path();
+	 * 	path.strokeColor = 'black';
+	 * 	path.add(event.point);
+	 * 	path.selected = true;
+	 * }
+	 * 
+	 * function onMouseDrag(event) {
+	 * 	// On every drag event, add a segment to the path
+	 * 	// at the position of the mouse:
+	 * 	path.add(event.point);
+	 * }
+	 * 
+	 * function onMouseUp(event) {
+	 * 	// When the mouse is released, simplify the path using
+	 * 	// the pointsToCurves function:
+	 * 	path.pointsToCurves();
+	 * 	path.selected = true;
+	 * }
+	 */
 	pointsToCurves: function(tolerance) {
 		var fitter = new PathFitter(this, tolerance || 2.5);
 		this.setSegments(fitter.fit());
@@ -1789,9 +1825,52 @@ var Path = this.Path = PathItem.extend({
 			this._add(segments);
 		},
 
-		// DOCS: document Path#lineBy
 		/**
-		 * @param {Point} vector
+		 * Adds a segment relative to the last segment point of the path.
+		 * 
+		 * @param {Point} vector The vector which is added to the position
+		 * of the last segment of the path, to become the new segment.
+		 * 
+		 * @example {@paperscript}
+		 * var path = new Path();
+		 * path.strokeColor = 'black';
+		 * 
+		 * // Add a segment at {x: 50, y: 50}
+		 * path.add(25, 25);
+		 * 
+		 * // Add a segment relative to the last segment of the path.
+		 * // 50 in x direction and 0 in y direction, becomes {x: 75, y: 25}
+		 * path.lineBy(50, 0);
+		 * 
+		 * // 0 in x direction and 50 in y direction, becomes {x: 75, y: 75}
+		 * path.lineBy(0, 50);
+		 * 
+		 * @example {@paperscript height=300}
+		 * // Drawing a spiral using lineBy:
+		 * var path = new Path();
+		 * path.strokeColor = 'black';
+		 * 
+		 * // Add the first segment at {x: 50, y: 50}
+		 * path.add(view.center);
+		 * 
+		 * // Loop 500 times:
+		 * for (var i = 0; i < 500; i++) {
+		 * 	// Create a vector with an ever increasing length
+		 * 	// and an angle in increments of 45 degrees
+		 * 	var vector = new Point({
+		 * 	    angle: i * 45,
+		 * 	    length: i / 2
+		 * 	});
+		 * 	// Add the vector relatively to the last segment point:
+		 * 	path.lineBy(vector);
+		 * }
+		 * 
+		 * // Smooth the handles of the path:
+		 * path.smooth();
+		 * 
+		 * // Uncomment the following line and click on 'run' to see
+		 * // the construction of the path:
+		 * // path.selected = true;
 		 */
 		lineBy: function(vector) {
 			vector = Point.read(arguments);
@@ -1828,6 +1907,8 @@ var Path = this.Path = PathItem.extend({
 		/**
 		 * Closes the path. When closed, Paper.js connects the first and last
 		 * segments.
+		 * 
+		 * @see #closed
 		 */
 		closePath: function() {
 			this.setClosed(true);

src/project/Project.js

@@ -66,24 +66,24 @@ var Project = this.Project = Base.extend({
 	 * @type PathStyle
 	 * @bean
 	 * 
-	 * @example
+	 * @example {@paperscript}
 	 * project.currentStyle = {
 	 * 	fillColor: 'red',
 	 * 	strokeColor: 'black',
 	 * 	strokeWidth: 5
 	 * }
 	 * 
-	 * // The following path will take over all style properties of
+	 * // The following paths 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
+	 * var path = new Path.Circle(new Point(75, 50), 30);
+	 * var path2 = new Path.Circle(new Point(175, 50), 20);
 	 * 
-	 * @example
+	 * @example {@paperscript}
 	 * 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)
+	 * var path = new Path.Circle(new Point(75, 50), 30);
+	 * var path2 = new Path.Circle(new Point(175, 50), 20);
 	 */
 	getCurrentStyle: function() {
 		return this._currentStyle;

src/text/TextItem.js

@@ -44,6 +44,31 @@ var TextItem = this.TextItem = Item.extend({
 	 *
 	 * @name TextItem#content
 	 * @type String
+	 * 
+	 * @example {@paperscript}
+	 * // Setting the content of a PointText item:
+	 * 
+	 * // Create a point-text item at {x: 30, y: 30}:
+	 * var text = new PointText(new Point(30, 30));
+	 * text.fillColor = 'black';
+	 * 
+	 * // Set the content of the text item:
+	 * text.content = 'Hello world';
+	 * 
+	 * @example {@paperscript}
+	 * // Interactive example, move your mouse over the view below:
+	 * 
+	 * // Create a point-text item at {x: 30, y: 30}:
+	 * var text = new PointText(new Point(30, 30));
+	 * text.fillColor = 'black';
+	 * 
+	 * text.content = 'Move your mouse over the view, to see its position';
+	 * 
+	 * function onMouseMove(event) {
+	 * 	// Each time the mouse is moved, set the content of
+	 * 	// the point text to describe the position of the mouse:
+	 * 	text.content = 'Your position is: ' + event.point.toString();
+	 * }
 	 */
 
 	_clone: function(copy) {

src/ui/View.js

@@ -146,7 +146,7 @@ var View = this.View = Base.extend({
 	},
 
 	/**
-	 * @type Size
+	 * @type Rectangle
 	 * @bean
 	 */
 	getBounds: function() {
@@ -269,17 +269,17 @@ var View = this.View = Base.extend({
 	 * <b>{@code event.delta}</b>: the time passed in seconds since the last frame
 	 * event.
 	 * 
-	 * @example
+	 * @example {@paperscript}
 	 * // Creating an animation:
 	 * 
-	 * // Create a rectangle shaped path between {x: 20, y: 20}
-	 * // and {x: 50, y: 50}:
-	 * var path = new Path.Rectangle([20, 20], [50, 50]);
+	 * // Create a rectangle shaped path with its top left point at:
+	 * // {x: 50, y: 25} and a size of {width: 50, height: 50}
+	 * var path = new Path.Rectangle(new Point(50, 25), new Size(50, 50));
 	 * path.fillColor = 'black';
 	 * 
 	 * function onFrame(event) {
-	 * 	// Every frame, rotate the path by 1 degree:
-	 * 	path.rotate(1);
+	 * 	// Every frame, rotate the path by 3 degrees:
+	 * 	path.rotate(3);
 	 * }
 	 * 
 	 * @type function
@@ -386,13 +386,13 @@ var View = this.View = Base.extend({
 				curPoint = point || curPoint;
 				if (curPoint)
 					tool.onHandleEvent('mousedrag', curPoint, event);
-				if (tool.onMouseDrag)
+				if (tool.onMouseDrag && !tool.onFrame)
 					that.draw();
 			// PORT: If there is only an onMouseMove handler, also call it when
 			// the user is dragging:
 			} else if (!dragging || onlyMove) {
 				tool.onHandleEvent('mousemove', point, event);
-				if (tool.onMouseMove)
+				if (tool.onMouseMove && !tool.onFrame)
 					that.draw();
 			}
 		}