EventProcessor

The Core.Web.Event namespace provides a higher-level cross-platform API for managing DOM events.

As previously discussed in the DOM Manipulation section, the Internet Explorer browser does not support the W3C DOM Events API. The utility methods in the Core.Web.DOM namespace somewhat work around this problem by providing cross-platform methods that delegate to the appropriate browser-specific method for event management. Unfortunately the event API of the Internet Explorer browser is also missing substantial functionality that is quite desirable when using a browser as an application user interface.

The critical omission from the Internet Explorer event API is that it does not support event capturing as specified in the W3C DOM Events API. Event capturing allows higher-level DOM elements to process events generated by their child elements before the child elements do so. Event capturing is of great benefit for a user interface toolkit. For example, a DHTML-rendered window might want the opportunity to raise itself when a contained button is clicked, before the button consumes the event.

The event processor provides a central registry of DOM events. Listeners may be registered to receive events during either the capturing or bubbling phase:

  • Capturing Phase: Events are processed by the highest-level element of the DOM first, and then by every ancestor of the element firing the event, from the top-down, until the target element is reached. The capturing phase occurs before the bubbling phase. If any element consumes the event, the bubbling phase will not occur.
  • Bubbling Phase: Events are processed first by the DOM element on which they are registered, and then on every ancestor element from the bottom-up, until the root element of the DOM is reached. In most cases you will want to register events in the bubbling phase.

Using the Event Processor

The API of the event processor is similar to that used in the Core.Web.DOM namespace for event listener registration. The add() and remove() methods can be used to register individual listeners. An additional removeAll() method provides the capability to unregister all event listeners for a specific element, which is typically used to clear all event listeners when an element is about to be destroyed.

Event listeners registered using the event processor may return a value of true to indicate that the event may continue bubbling, or false to indicate that it should not. Not returning a value is the same as returning false, and will cancel bubbling.