CBE Event Model Cross-Browser.com 

CBE Event Model

Implementing The W3C DOM2 Event Model

Overview

It will be helpful to first read about the CBE core object model.

The CBE Event Model is an implementation of the W3C DOM2 event model. Like the CBE core object model, it involves only CrossBrowserElement objects. Event listeners receive CrossBrowserEvent object arguments. CrossBrowserEvent objects flow up and down the CBE object tree in different phases of the event. You can add more than one listener of a particular event type to an object!

Event Listeners

An event listener is just an event handler function you provide. The function will receive one argument, a CrossBrowserEvent object. You add (or register) an event listener to a specific CrossBrowserElement object by calling the object's addEventListener() method. Let's look at it's syntax:

addEventListener(eventType, eventListener, useCapture)

The eventType argument is a string such as "mouseOver". The eventListener argument is a reference to a function. The useCapture argument is boolean.

In listing 1 a mouseOver event listener is added to the E1 element. When the mouse first moves over the element, the function mouseOverListener will be called and passed a CrossBrowserEvent object as an argument.

Listing 1

function windowOnload() {
  var e1 = document.getElementById('E1').cbe;
  e1.addEventListener('mouseOver', mouseOverListener, false);
}

function mouseOverListener(e) {
  alert('The mouse is over ' + e.cbeCurrentTarget.id);
}

Event listeners are removed by calling the object's removeEventListener() method. It must be passed the same arguments as were passed to addEventListener().

Basic Event Flow

CrossBrowserEvent objects are only sent to CrossBrowserElement objects. When an event occurs, a specific CrossBrowserElement object is designated as the event target, and is specified in the event object's cbeTarget property. The event then travels up and down the CBE object tree looking for event listeners registered on the same event type as the event. This occurs in three distinct phases, in this order: the CAPTURING_PHASE, the AT_TARGET phase, and the BUBBLING_PHASE.

After an event target has been designated, an array is built which consists of every CrossBrowserElement object along the parent chain between the event target and the root of the object tree, but not including the event target. This parent chain array is used during the capturing and bubbling phases.

The Capturing Phase

The capturing phase begins at the top node of the parent chain - at window.cbe. The node then dispatches the event to all event listeners that have been added to the node that have the same type as the event and that had passed useCapture==true in the call to addEventListener(). The next node in the parent chain then dispatches the event. This continues down the parent chain until the parent of the event target node dispatches the event to it's listeners.

A capturing event listener will not be triggered by events dispatched directly (AT_TARGET) to the event target upon which it is registered.

The At-Target Phase

After the capturing phase, the at-target phase begins. The event target node dispatches the event to all event listeners that have been added to the node that have the same type as the event and that had passed useCapture==false in the call to addEventListener().

The Bubbling Phase

After the at-target phase, the bubbling phase begins. This phase begins at the parent of the event target. This node dispatches the event to all event listeners that have been added to the node that have the same type as the event and that had passed useCapture==false in the call to addEventListener(). Then the parent of that node dispatches the event. This continues up the parent chain until the root node of the object tree dispatches the event to it's listeners. Event listeners registered as capturers will not be triggered during this phase.

CrossBrowserEvent

The CrossBrowserEvent object is a partial implementation of some of the W3C DOM2 Event interfaces. See the reference for details on each property.

cbeTarget & cbeCurrentTarget

When a listener receives an event, the event object's cbeCurrentTarget property points to the CrossBrowserElement object of the current listener. Effectively, it is the listener's this pointer. The event object's cbeTarget property points to the CrossBrowserElement object which is the actual target of the event.

stopPropagation() & preventDefault()

If an event listener wishes to prevent further propagation of the event (stop/prevent the capturing or bubbling phase) it may call the stopPropagation() method of the event object. This will prevent further propagation of the event, although the event will still be dispatched to any remaining event listeners registered on the same object.

An EventListener may call the preventDefault() method of the event object to cancel any default action associated with the event.

CBE Supported Events

The following events are supported by this implementation of the DOM2 event model.

  • click
  • mousedown
  • mouseup
  • mousemove
  • mouseover
  • mouseout
  • keypress
  • keyup
  • keydown

CBE also provides support for the following events but not yet within the new event model.

  • drag
  • dragStart
  • dragEnd
  • slide
  • slideStart
  • slideEnd
  • dragResize (specialized)
  • scroll (for window object)
  • resize (for window object)

See the object reference for details on CrossBrowserElement events.