From 1414500f45ae6570a6400cfb0a2176ddc9bbfe03 Mon Sep 17 00:00:00 2001
From: Jonathan Puckey <me@jonathanpuckey.com>
Date: Thu, 1 Dec 2011 11:57:10 +0100
Subject: [PATCH] First version of documentation of Item event handlers and
MouseEvent.
---
src/item/Item.js | 252 +++++++++++++++++++++++++++++++++++++++++++
src/ui/MouseEvent.js | 37 ++++++-
2 files changed, 288 insertions(+), 1 deletion(-)
diff --git a/src/item/Item.js b/src/item/Item.js
index 23873d4f..f5217159 100644
--- a/src/item/Item.js
+++ b/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;
diff --git a/src/ui/MouseEvent.js b/src/ui/MouseEvent.js
index 46e14651..7582f691 100644
--- a/src/ui/MouseEvent.js
+++ b/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