Skip to content
Browse files

doc: Merge/update old Event overview docs into source [#93 state:fixe…

…d_in_branch]
  • Loading branch information...
1 parent 0412f66 commit ae03e319674941a4c07531415827ff589a43399a Tim Walker committed with samleb Feb 20, 2010
Showing with 43 additions and 2 deletions.
  1. +43 −2 src/dom/event.js
View
45 src/dom/event.js
@@ -5,7 +5,7 @@
*
* The namespace for Prototype's event system.
*
- * <h5>Events: a fine mess</h5>
+ * ##### Events: a fine mess
*
* Event management is one of the really sore spots of cross-browser
* scripting.
@@ -17,7 +17,7 @@
* Safari). Also, MSIE has a tendency to leak memory when it comes to
* discarding event handlers.
*
- * <h5>Prototype to the rescue</h5>
+ * ##### Prototype to the rescue
*
* Of course, Prototype smooths it over so well you'll forget these
* troubles even exist. Enter the `Event` namespace. It is replete with
@@ -33,6 +33,35 @@
* The functions you're most likely to use a lot are [[Event.observe]],
* [[Event.element]] and [[Event.stop]]. If your web app uses custom events,
* you'll also get a lot of mileage out of [[Event.fire]].
+ *
+ * ##### Instance methods on event objects
+ * As of Prototype 1.6, all methods on the `Event` object are now also
+ * available as instance methods on the event object itself:
+ *
+ * **Before**
+ *
+ * $('foo').observe('click', respondToClick);
+ *
+ * function respondToClick(event) {
+ * var element = Event.element(event);
+ * element.addClassName('active');
+ * }
+ *
+ * **After**
+ *
+ * $('foo').observe('click', respondToClick);
+ *
+ * function respondToClick(event) {
+ * var element = event.element();
+ * element.addClassName('active');
+ * }
+ *
+ * These methods are added to the event object through [[Event.extend]],
+ * in the same way that `Element` methods are added to DOM nodes through
+ * [[Element.extend]]. Events are extended automatically when handlers are
+ * registered with Prototype's [[Event.observe]] method; if you're using a
+ * different method of event registration, for whatever reason,you'll need to
+ * extend these events manually with [[Event.extend]].
**/
var Event = {
KEY_BACKSPACE: 8,
@@ -351,6 +380,18 @@
inspect: function() { return '[object Event]' }
});
+ /**
+ * Event.extend(@event) -> Event
+ *
+ * Extends `event` with all of the methods contained in `Event.Methods`.
+ *
+ * Note that all events inside handlers that were registered using
+ * [[Event.observe]] or [[Element.observe]] will be extended automatically.
+ *
+ * You need only call `Event.extend` manually if you register a handler a
+ * different way (e.g., the `onclick` attribute). We really can't encourage
+ * that sort of thing, though.
+ **/
// IE's method for extending events.
Event.extend = function(event, element) {
if (!event) return false;

0 comments on commit ae03e31

Please sign in to comment.
Something went wrong with that request. Please try again.