Event.stopObserving(element, eventName, handler)

Unregisters one or more event handlers.

This function unregisters event handlers registered via Event.observe. As of v1.6, it takes three forms:

• Remove a specific handler: If you provide all three arguments, the specific handler you list is unregistered. You must provide the exact same arguments you provided to Event.observe (see "Why won't it stop observing?" below).
• Remove all handlers for an event: If you provide element and eventName but not handler, all handlers for that event on that element are unregistered. (New in 1.6)
• Remove all handlers: If you just provide element and not the other two arguments, all handlers for all events on that element are removed. (New in 1.6)

Examples:

Unregister fooClickHandler from the 'click' event on the element with the ID "foo":

Event.stopObserving('foo', 'click', fooClickHandler);
// or
$('foo').stopObserving('click', fooClickHandler);

Unregister all 'click' handlers on the element with the ID "foo":

Event.stopObserving('foo', 'click');
// or
$('foo').stopObserving('click');

Unregister all handlers on the element with the ID "foo" (perhaps you're about to remove foo from the DOM):

Event.stopObserving('foo');
// or
$('foo').stopObserving();

Why won't it stop observing!?

When you're using the three-argument form to unregister a specific handler, for stopObserving to work you must pass exactly the same arguments as those you did to the corresponding observe call. Complying with this seems straightforward enough, but there is a common pattern where code is not what it seems to be:

var obj = {
  …
  fx: function(event) {
    …
  }
};

Event.observe(elt, 'click', obj.fx.bindAsEventListener(obj));
…

// THIS IS WRONG, DON'T DO IT!
Event.stopObserving(elt, 'click', obj.fx.bindAsEventListener(obj)); // Won't work!

Here, although it may seem fine at first glance, you must remember that bindAsEventListener returns a fresh anonymous function that wraps your method. This means that every call to it returns a new function. Therefore, the code above requests stopping on another function than was used when setting up observation. No match is found, and the original observer is left untroubled.

To avoid this, you need to "cache" the bound functions (which is, for instance, what script.aculo.us does in many of its classes), like th is:

var obj = {
  …
  fx: function(event) {
    …
  },
};

obj.bfx = obj.fx.bindAsEventListener(obj);

Event.observe(elt, 'click', obj.bfx);
…
Event.stopObserving(elt, 'click', obj.bfx);

See also

The unloadCache function is related and worth a look.