First version of documentation of Item event handlers and MouseEvent.

src/item/Item.js

@@ -101,6 +101,258 @@ var Item = this.Item = Base.extend(Callback, /** @lends Item# */{
 			});
 	},
 
+	// DOCS: move event handler documentation down?
+	/**
+	 * {@grouptitle Event Handlers}
+	 * Item level handler function to be called on each frame of an animation.
+	 * The function receives an event object which contains information about
+	 * the frame event:
+	 *
+	 * <b>{@code event.count}</b>: the number of times the frame event was
+	 * fired.
+	 * <b>{@code event.time}</b>: the total amount of time passed since the
+	 * first frame event in seconds.
+	 * <b>{@code event.delta}</b>: the time passed in seconds since the last
+	 * frame event.
+	 *
+ 	 * @see View#onFrame
+	 * @example {@paperscript}
+	 * // Creating an animation:
+	 *
+	 * // 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';
+	 *
+	 * path.onFrame = function(event) {
+	 * 	// Every frame, rotate the path by 3 degrees:
+	 * 	this.rotate(3);
+	 * }
+	 *
+	 * @name Item#onFrame
+	 * @property
+	 * @type Function
+	 */
+
+	/**
+	 * The function to be called when the mouse button is pushed down on the
+	 * item. The function receives a {@link MouseEvent} object which contains
+	 * information about the mouse event.
+	 *
+	 * @name Item#onMouseDown
+	 * @property
+	 * @type Function
+	 *
+	 * @example {@paperscript}
+	 * // Press the mouse button down on the circle shaped path, to make it red:
+	 * 
+	 * // Create a circle shaped path at the center of the view:
+	 * var path = new Path.Circle(view.center, 25);
+	 * path.fillColor = 'black';
+	 * 
+	 * // When the mouse is pressed on the item,
+	 * // set its fill color to red:
+	 * path.onMouseDown = function(event) {
+	 * 	this.fillColor = 'red';
+	 * }
+	 * 
+	 * @example {@paperscript}
+	 * // Press the mouse on the circle shaped paths to remove them:
+	 * 
+	 * // Loop 30 times:
+	 * for (var i = 0; i < 30; i++) {
+	 * 	// Create a circle shaped path at a random position
+	 * 	// in the view:
+	 * 	var position = Point.random() * view.size;
+	 * 	var path = new Path.Circle(position, 25);
+	 * 	path.fillColor = 'black';
+	 * 	path.strokeColor = 'white';
+	 * 	// When the mouse is pressed on the item, remove it:
+	 * 	path.onMouseDown = function(event) {
+	 * 		this.remove();
+	 * 	}
+	 * }
+	 */
+
+	/**
+	 * The function to be called when the mouse button is released over the item.
+	 * The function receives a {@link MouseEvent} object which contains
+	 * information about the mouse event.
+	 *
+	 * @name Item#onMouseUp
+	 * @property
+	 * @type Function
+	 *
+	 * @example {@paperscript}
+	 * // Release the mouse button over the circle shaped path, to make it red:
+	 * 
+	 * // Create a circle shaped path at the center of the view:
+	 * var path = new Path.Circle(view.center, 25);
+	 * path.fillColor = 'black';
+	 * 
+	 * // When the mouse is released over the item,
+	 * // set its fill color to red:
+	 * path.onMouseUp = function(event) {
+	 * 	this.fillColor = 'red';
+	 * }
+	 */
+
+	/**
+	 * The function to be called when the mouse clicks on the item. The function
+	 * receives a {@link MouseEvent} object which contains information about the
+	 * mouse event.
+	 *
+	 * @name Item#onClick
+	 * @property
+	 * @type Function
+	 *
+	 * @example {@paperscript}
+	 * // Click on the circle shaped path, to make it red:
+	 * 
+	 * // Create a circle shaped path at the center of the view:
+	 * var path = new Path.Circle(view.center, 25);
+	 * path.fillColor = 'black';
+	 * 
+	 * // When the mouse is clicked on the item,
+	 * // set its fill color to red:
+	 * path.onClick = function(event) {
+	 * 	this.fillColor = 'red';
+	 * }
+	 * 
+	 * @example {@paperscript}
+	 * // Click on the circle shaped paths to remove them:
+	 * 
+	 * // Loop 30 times:
+	 * for (var i = 0; i < 30; i++) {
+	 * 	// Create a circle shaped path at a random position
+	 * 	// in the view:
+	 * 	var position = Point.random() * view.size;
+	 * 	var path = new Path.Circle(position, 25);
+	 * 	path.fillColor = 'black';
+	 * 	path.strokeColor = 'white';
+	 * 	// When the mouse is clicked on the item, remove it:
+	 * 	path.onClick = function(event) {
+	 * 		this.remove();
+	 * 	}
+	 * }
+	 */
+
+	/**
+	 * The function to be called when the mouse double clicks on the item. The
+	 * function receives a {@link MouseEvent} object which contains information
+	 * about the mouse event.
+	 *
+	 * @name Item#onDoubleClick
+	 * @property
+	 * @type Function
+	 *
+	 * @example {@paperscript}
+	 * // Double click on the circle shaped path, to make it red:
+	 * 
+	 * // Create a circle shaped path at the center of the view:
+	 * var path = new Path.Circle(view.center, 25);
+	 * path.fillColor = 'black';
+	 * 
+	 * // When the mouse is double clicked on the item,
+	 * // set its fill color to red:
+	 * path.onDoubleClick = function(event) {
+	 * 	this.fillColor = 'red';
+	 * }
+	 * 
+	 * @example {@paperscript}
+	 * // Double click on the circle shaped paths to remove them:
+	 * 
+	 * // Loop 30 times:
+	 * for (var i = 0; i < 30; i++) {
+	 * 	// Create a circle shaped path at a random position
+	 * 	// in the view:
+	 * 	var position = Point.random() * view.size;
+	 * 	var path = new Path.Circle(position, 25);
+	 * 	path.fillColor = 'black';
+	 * 	path.strokeColor = 'white';
+	 * 	// When the mouse is clicked on the item, remove it:
+	 * 	path.onDoubleClick = function(event) {
+	 * 		this.remove();
+	 * 	}
+	 * }
+	 */
+
+	/**
+	 * The function to be called repeatedly when the mouse moves on top of the
+	 * item. The function receives a {@link MouseEvent} object which contains
+	 * information about the mouse event.
+	 *
+	 * @name Item#onMouseMove
+	 * @property
+	 * @type Function
+	 *
+	 * @example {@paperscript}
+	 * // Move over the circle shaped path, to change its opacity:
+	 * 
+	 * // Create a circle shaped path at the center of the view:
+	 * var path = new Path.Circle(view.center, 25);
+	 * path.fillColor = 'black';
+	 * 
+	 * // When the mouse moves on top of the item, set its opacity
+	 * // to a random value between 0 and 1:
+	 * path.onMouseMove = function(event) {
+	 * 	this.opacity = Math.random();
+	 * }
+	 */
+
+	/**
+	 * The function to be called when the mouse moves over the item. This
+	 * function will only be called again, once the mouse moved outside of the
+	 * item first. The function receives a {@link MouseEvent} object which
+	 * contains information about the mouse event.
+	 *
+	 * @name Item#onMouseEnter
+	 * @property
+	 * @type Function
+	 *
+	 * @example {@paperscript}
+	 * // When you move the mouse over the item, its fill color is set to red.
+	 * // When you move the mouse outside again, its fill color is set back
+	 * // to black.
+	 * 
+	 * // Create a circle shaped path at the center of the view:
+	 * var path = new Path.Circle(view.center, 25);
+	 * path.fillColor = 'black';
+	 * 
+	 * // When the mouse enters the item, set its fill color to red:
+	 * path.onMouseEnter = function(event) {
+	 * 	this.fillColor = 'red';
+	 * }
+	 
+	 * // When the mouse leaves the item, set its fill color to black:
+	 * path.onMouseLeave = function(event) {
+	 * 	this.fillColor = 'black';
+	 * }
+	 */
+
+	/**
+	 * The function to be called when the mouse moves out of the item.
+	 * The function receives a {@link MouseEvent} object which contains
+	 * information about the mouse event.
+	 *
+	 * @name Item#onMouseLeave
+	 * @property
+	 * @type Function
+	 *
+	 * @example {@paperscript}
+	 * // Move the mouse over the circle shaped path and then move it out
+	 * // of it again to set its fill color to red:
+	 * 
+	 * // Create a circle shaped path at the center of the view:
+	 * var path = new Path.Circle(view.center, 25);
+	 * path.fillColor = 'black';
+	 * 
+	 * // When the mouse leaves the item, set its fill color to red:
+	 * path.onMouseLeave = function(event) {
+	 * 	this.fillColor = 'red';
+	 * }
+	 */
+
 	initialize: function() {
 		// Define this Item's unique id.
 		this._id = ++Item._id;

src/ui/MouseEvent.js

@@ -17,6 +17,13 @@
 /**
  * @name MouseEvent
  *
+ * @class MouseEvent The MouseEvent object is received by the {@link Item}'s
+ * mouse event handlers {@link Item#onMouseDown}, {@link Item#onMouseDrag},
+ * {@link Item#onMouseMove}, {@link Item#onMouseUp}, {@link Item#onClick},
+ * {@link Item#onDoubleClick}, {@link Item#onMouseEnter} and
+ * {@link Item#onMouseLeave}. The MouseEvent object is the only parameter passed
+ * to these functions and contains information about the mouse event.
+ *
  * @extends Event
  */
 var MouseEvent = this.MouseEvent = Event.extend(/** @lends MouseEvent# */{
@@ -29,7 +36,35 @@ var MouseEvent = this.MouseEvent = Event.extend(/** @lends MouseEvent# */{
 	},
 
 	/**
-	 * @return {String} A string representation of the key event.
+	 * The type of mouse event.
+	 *
+	 * @name MouseEvent#type
+	 * @type String('mousedown', 'mouseup', 'mousedrag', 'click',
+	 * 'doubleclick', 'mousemove', 'mouseenter', 'mouseleave')
+	 */
+
+	/**
+	 * The position of the mouse in project coordinates when the event was
+	 * fired.
+	 *
+	 * @name MouseEvent#point
+	 * @type Point
+	 */
+
+	// DOCS: document MouseEvent#target
+	/**
+	 * @name MouseEvent#target
+	 * @type Item
+	 */
+
+	// DOCS: document MouseEvent#delta
+	/**
+	 * @name MouseEvent#delta
+	 * @type Point
+	 */
+
+	/**
+	 * @return {String} A string representation of the mouse event.
 	 */
 	toString: function() {
 		return '{ type: ' + this.type