Event Atom feed
♪ What a wonderful mess (it would be) ♫
Event management is one of the really sore spots of cross-browser scripting.
True, the prominent issue is: everybody does it the W3C way, and MSIE does it another way altogether. But there are quite a few subtler, sneakier issues here and there waiting to bite your ankle, such as the keypress
/keydown
issue with KHTML-based browsers (Konqueror and Safari). Also, MSIE has a tendency to leak memory when it comes to discarding event handlers.
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 methods (listed at the top and bottom of this page), that all take the current event object as an argument, and happily produce the information you’re requesting, across all major browsers.
Event
also provides a standardized list of key codes you can use with keyboard-related events. The following constants are defined in the namespace: KEY_BACKSPACE
, KEY_TAB
, KEY_RETURN
, KEY_ESC
, KEY_LEFT
, KEY_UP
, KEY_RIGHT
, KEY_DOWN
, KEY_DELETE
, KEY_HOME
, KEY_END
, KEY_PAGEUP
, KEY_PAGEDOWN
. The names are self-explanatory.
The functions you’re most likely to use a lot are observe
, element
and stop
. As for the others, your mileage may vary; it’s all about what your web app does.
Instance methods on event objects 1.6
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
.
Methods
element
Event.element(event) -> Element
Returns the DOM element on which the event occurred.
extend
1.6
Event.extend(event)
Extends event
with all of the methods contained in Event.Methods
.
findElement
Event.findElement(event, tagName) -> Element
Returns the first DOM element with a given tag name, upwards from the one on which the event occurred.
isLeftClick
Event.isLeftClick(event) -> Boolean
Determines whether a button-related mouse event was about the “left” (primary, actually) button.
observe
Event.observe(element, eventName, handler)
Registers an event handler on a DOM element.
pointerX
Event.pointerX(event) -> Number
Returns the absolute horizontal position for a mouse event.
pointerY
Event.pointerY(event) -> Number
Returns the absolute vertical position for a mouse event.
stop
Event.stop(event)
Stops the event’s propagation and prevents its default action from being triggered eventually.
stopObserving
Event.stopObserving(element, eventName, handler)
Unregisters one or more event handlers.
unloadCache
1.6
Event.unloadCache()
Unregisters all event handlers registered through observe
. Automatically wired for you. Not available since 1.6.