diff --git a/src/item/Item.js b/src/item/Item.js index fea53f2c..f990912a 100644 --- a/src/item/Item.js +++ b/src/item/Item.js @@ -1962,6 +1962,409 @@ function(name) { : ' @' + this._id); }, + /** + * {@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: + * + * {@code event.count}: the number of times the frame event was + * fired. + * {@code event.time}: the total amount of time passed since the + * first frame event in seconds. + * {@code event.delta}: 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'; + * } + * @example {@paperscript} + * // When you click the mouse, you create new circle shaped items. 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. + * + * function enter(event) { + * this.fillColor = 'red'; + * } + * + * function leave(event) { + * this.fillColor = 'black'; + * } + * + * // When the mouse is pressed: + * function onMouseDown(event) { + * // Create a circle shaped path at the position of the mouse: + * var path = new Path.Circle(event.point, 25); + * path.fillColor = 'black'; + * + * // When the mouse enters the item, set its fill color to red: + * path.onMouseEnter = enter; + * + * // When the mouse leaves the item, set its fill color to black: + * path.onMouseLeave = leave; + * } + */ + + /** + * 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'; + * } + */ + + /** + * {@grouptitle Event Handling} + * + * Attach an event handler to the item. + * + * @name Item#attach + * @function + * @param {String('mousedown', 'mouseup', 'mousedrag', 'click', + * 'doubleclick', 'mousemove', 'mouseenter', 'mouseleave')} type the event + * type + * @param {Function} function The function to be called when the event + * occurs + * + * @example {@paperscript} + * // Change the fill color of the path to red when the mouse enters its + * // shape and back to black again, when it leaves its shape. + * + * // 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.attach('mouseenter', function() { + * this.fillColor = 'red'; + * }); + * + * // When the mouse leaves the item, set its fill color to black: + * path.attach('mouseleave', function() { + * this.fillColor = 'black'; + * }); + */ + /** + * Attach one or more event handlers to the item. + * + * @name Item#attach^2 + * @function + * @param {Object} param An object literal containing one or more of the + * following properties: {@code mousedown, mouseup, mousedrag, click, + * doubleclick, mousemove, mouseenter, mouseleave}. + * + * @example {@paperscript} + * // Change the fill color of the path to red when the mouse enters its + * // shape and back to black again, when it leaves its shape. + * + * // 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.attach({ + * mouseenter: function(event) { + * this.fillColor = 'red'; + * }, + * mouseleave: function(event) { + * this.fillColor = 'black'; + * } + * }); + * @example {@paperscript} + * // When you click the mouse, you create new circle shaped items. 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 black. + * + * var pathHandlers = { + * mouseenter: function(event) { + * this.fillColor = 'red'; + * }, + * mouseleave: function(event) { + * this.fillColor = 'black'; + * } + * } + * + * // When the mouse is pressed: + * function onMouseDown(event) { + * // Create a circle shaped path at the position of the mouse: + * var path = new Path.Circle(event.point, 25); + * path.fillColor = 'black'; + * + * // Attach the handers inside the object literal to the path: + * path.attach(pathHandlers); + * } + */ + + /** + * Detach an event handler from the item. + * + * @name Item#detach + * @function + * @param {String('mousedown', 'mouseup', 'mousedrag', 'click', + * 'doubleclick', 'mousemove', 'mouseenter', 'mouseleave')} type the event + * type + * @param {Function} function The function to be detached + */ + /** + * Detach one or more event handlers to the item. + * + * @name Item#detach^2 + * @function + * @param {Object} param An object literal containing one or more of the + * following properties: {@code mousedown, mouseup, mousedrag, click, + * doubleclick, mousemove, mouseenter, mouseleave} + */ + + /** + * Fire an event on the item. + * + * @name Item#fire + * @function + * @param {String('mousedown', 'mouseup', 'mousedrag', 'click', + * 'doubleclick', 'mousemove', 'mouseenter', 'mouseleave')} type the event + * type + * @param {Object} event An object literal containing properties describing + * the event. + */ + + /** + * Check if the item has one or more event handlers of the specified type. + * + * @name Item#responds + * @function + * @param {String('mousedown', 'mouseup', 'mousedrag', 'click', + * 'doubleclick', 'mousemove', 'mouseenter', 'mouseleave')} type the event + * type + * @return {Boolean} {@true if the item has one or more event handlers of + * the specified type} + */ + statics: { drawSelectedBounds: function(bounds, ctx, matrix) { var coords = matrix._transformCorners(bounds); 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 diff --git a/src/ui/View.js b/src/ui/View.js index 6139097c..f3fe2af9 100644 --- a/src/ui/View.js +++ b/src/ui/View.js @@ -432,7 +432,7 @@ var View = this.View = Base.extend(Callback, /** @lends View# */{ var view = View._views[i]; if (view && view.isVisible()) { View._focused = tempFocus = view; - throw Base.stop; + break; } } }