[DOML3Events] ACTION-267 Proposal for event iterator

In considering a design for the event iterator (allow devs to enumerate what events have been _added_ via addEventListener to a given object), I looked at too general approaches:

1) Defining a new collection on every object that supports the EventTarget interface
2) Defining a 'getNextEvent' function for every object that supports the EventTarget interface
3) Defining a function that returns a static/dynamic list of event handlers for a given object that supports the EventTarget interface

Ultimately, my design was to go with the 3rd option. Here's why:

Option 1 Pros:
* A collection property is easy to directly access via an object of interest
* A collection property is harmonious with other design decisions in the DOM (.childNodes, .attributes)

Option 1 Cons:
* There are many event 'types' that can be added to any given object as well as the characteristic of whether that listener is triggered on the capture/bubble phase, and a single collection merges all of these events in a way that is hard to split out individual types without the use of two keys (in other words, such a proposal would look a lot like the original HTML5-spec'd design for the globalStorage collection, except with two keys--unless we ignore the capture/bubble param).
* Requires a more rigid object or collection design than option 3.

Option 2 Pros:
* Supports the common incremental-access programming pattern (just get me the 'next' defined event handler, if any).

Option 2 Cons:
* Does not support the random-access programming pattern (see discussion on .childElements collection [1])

Option 3 Pros:
* The 'retrieval function' approach has precedence in other DOM specs, such as getComputedStyle(...) and querySelector(...) where the returned collection can be either LIVE or not depending on need.
* The 'retrieval function' appraoch can support multiple parameters that can alter the collection that gets returned. This seemed like the most natural approach given that event listeners always have at least two parameters (event type string and isCapture bool).
* Provides random-access and iterative access through the returned collection.

Option 3 Cons:
* Not as convenient as a direct-access collection property

Without futher ado, here's my proposal for DOM L3 Events per-object enumerator (with a little help from the current Bindings [2] spec).

=========================
IDL Definition // Introduced in DOM Level 2:

// New in DOM Level 3:
typedef sequence<EventListener> EventListenerList;

interface EventTarget {
  void               addEventListener(in DOMString type,
                                      in EventListener listener,
                                      in boolean useCapture);
  void               removeEventListener(in DOMString type,
                                         in EventListener listener,
                                         in boolean useCapture);
  // Modified in DOM Level 3:
  boolean            dispatchEvent(in Event evt)
                                        raises(EventException,
                                               DOMException);
  // Introduced in DOM Level 3:
  void               addEventListenerNS(in DOMString namespaceURI,
                                        in DOMString type,
                                        in EventListener listener,
                                        in boolean useCapture);
  // Introduced in DOM Level 3:
  void               removeEventListenerNS(in DOMString namespaceURI,
                                           in DOMString type,
                                           in EventListener listener,
                                           in boolean useCapture);
  // Introduced in DOM Level 3:
  EventListenerList  getEventListeners(in DOMString typeFilter,
                                       in boolean useCaptureFilter);
  // Introduced in DOM Level 3:
  EventListenerList  getEventListenersNS(in DOMString namespaceURIFilter,
                                         in DOMString typeFilter,
                                         in boolean useCaptureFilter);
};

* getEventListeners[NS] - each parameter is allowed to be null.

* If null is provided for all parameters, then the sequence of EventListeners returned includes all event listeners added 1) from all namespaces, 2) for all event types, and 3) in all event phases (capture/bubble).

* Providing a non-null value for any of the parameters to these methods filters the set of returned Event Listeners in the sequence. For example:
[EventTarget].getEventListeners('click', null);
 returns all of the 'click' events added to the object for all event phases.

* The sequence of EventListeners returned from this API _must_ be in the order in which said event listeners will fire on the object (i.e., the order must be [capture events first sorted in order in which they will be fired, then bubble events sorted in the order in which they will fire).

================
Travis Leithead - OM Program Manager - Internet Explorer

[1] http://lists.w3.org/Archives/Public/public-webapi/2008Apr/0001.html
[2] http://dev.w3.org/cvsweb/~checkout~/2006/webapi/Binding4DOM/Overview.html?rev=1.66&content-type=text/html;%20charset=iso-8859-1

Received on Wednesday, 9 April 2008 18:11:17 UTC