ISSUE-42: Should we simplify custom events?

simpler custom events

Should we simplify custom events?

HISTORICAL: DOM3 Events [All Bugs and Issues use Bugzilla:]
Raised by:
Doug Schepers
Opened on:
From Cameron McCormack in

I'd like to make another suggestion about DOM 3 custom events; this time
a great simplification.

Currently any custom event object that is to be dispatched to listeners
must implement the CustomEvent interface, and hence also the Event
interface. For ECMAScript, this means writing 10 methods for that
object--plus one more to get event dispatching working properly[1] and
another to make it work under sXBL[2]. For Java it's even worse, since
getter methods must be provided for the attributes, bringing the number
of methods to 20. Though a Java implementation could provide an
abstract custom event class to extend to ease that burden, this isn't
possible for ECMAScript if it's to be non-UA-specific.

The main reason for custom events is to associate extra attributes with
the event object specific to the event. As such, I think it's likely
overkill to allow user objects to be dispatched by the events
implementation. Instead, we could have a custom event object created
by the implementation, if this object has an attribute of type DOMObject
that holds all of the custom event object information.

interface CustomEvent : Event {
readonly attribute DOMObject details;

void initCustomEventNS(in DOMString namespaceURIArg,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in DOMObject detailsArg);

These custom event objects could be then created with a call to
DocumentEvent.createEvent("CustomEvent"). For example in ECMAScript:

var currentTime = ...;
var evt = document.createEvent("CustomEvent");
true, false, { time: currentTime });

If specifying whether custom events should be retargetted or stopped at
shadow scope boundaries under sXBL is a desirable feature (and I think
it is), then a separate interface to set this information is probably
the way to go.

interface EventXBL {
attribute boolean retargetable;

All event objects created by an sXBL capable events implementation would
implement this interface. The retargetable attribute would be set to
the appropriate value when methods such as UIEvent.initUIEventNS,
MutationEvent.initMutationEventNS, etc. are called. For events without
an intrinsic retargetability (such as those initialised with
Event.initEventNS or CustomEvent.initCustomEventNS), it would default to
a particular value (not sure what would be the more appropriate default

If a CustomEvent were retargetted, its details attribute would be copied
to the clone.

I think this is much simpler than what is currently specified, as
demonstrated by this[3] ECMAScript example.

Please let me know your thoughts on this suggestion.



Related Actions Items:
No related actions
Related emails:
  1. Re: ISSUE-42 (simpler custom events): Should we simplify custom events? [DOM3 Events] (from on 2008-07-24)
  2. Re: ISSUE-42 (simpler custom events): Should we simplify custom events? [DOM3 Events] (from on 2008-07-24)
  3. Re: ISSUE-42 (simpler custom events): Should we simplify custom events? [DOM3 Events] (from on 2008-07-23)
  4. ISSUE-42 (simpler custom events): Should we simplify custom events? [DOM3 Events] (from on 2008-07-23)

Related notes:


Doug Schepers, 18 Aug 2010, 18:31:27

Display change log ATOM feed

Chair, Staff Contact
Tracker: documentation, (configuration for this group), originally developed by Dean Jackson, is developed and maintained by the Systems Team <>.
$Id: 42.html,v 1.1 2016/01/25 10:26:20 carine Exp $