W3C

DOM4 Events

5 October 2011

This version:
TBD
Latest published version:
TBD
Latest editor's draft:
http://dvcs.w3.org/hg/d4e/raw-file/tip/source_respec.htm
Previous version:
none
Editor:
Jacob Rossi, Microsoft Corporation

Abstract

This proposed specification defines the Document Object Model Events Level 4, which builds on the event model defined in the [Document Object Model Events Level 3].

Status of This Document

Note: This specification is now being edited in the W3C Web Applications (WebApps) Working Group. Please see the latest Editor's Draft.

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document was published by Microsoft Corporation as a proposed specification for the W3C Web Applications (WebApps) Working Group. If you wish to make comments regarding this document, please send them to public-webapps@w3.org (subscribe, archives). All feedback is welcome.

Publication as a Unofficial Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Introduction

1.1 Goals

DOM4 Events builds on the event model defined in DOM Level 3 Events (and also DOM4). Features in scope for this specification are as follows:

1.2 Conformance Criteria

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]

Requirements phrased in the imperative as part of algorithms(such as "strip any leading space characters" or "return false and terminate these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

User agents may impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.

When a method or an attribute is said to call another method or attribute, the user agent must invoke its internal API for that attribute or method so that e.g. the author can't change the behavior by overriding attributes or methods with custom properties or functions in ECMAScript.

Unless otherwise stated, string comparisons are done in a case-sensitive manner.

1.3 Feature Detection

A conforming DOM4 Events user agent must implement the DOMImplementation.hasFeature() method to allow content authors to detect for support of features defined in this specification. Refer to DOM Features in [DOM3 Core] for additional information on feature strings.

A user agent conforming to DOM4 Events must also implement the following feature string convention for describing DOM3 Events feature support:

2. Event Constructors

2.1 Overview

This section is informative

For each event interface defined in [DOM3 Events], there exists an initialization method for synthesizing untrusted events. This mechanism does not scale well to event interfaces with many members. Event Constructors (introduced for the Event interface in [DOM4]) are a mechanism for creating and initializing untrusted event objects more easily.

Synthesizing an untrusted event using legacy initialization methods:

var event = document.createEvent("MouseEvent");
event.initMouseEvent("mouseover",
    true,
    true,
    window,
    null,
    null,
    null,
    0,
    0,
    null,
    null,
    null,
    null,
    previousEventTarget);
eventTarget.dispatchEvent(event);	
 

Synthesizing an untrusted event using constructors:

var event = new MouseEvent("mouseover",
   {bubbles: true, 
    cancelable: true, 
    relatedTarget: previousEventTarget
    });
eventTarget.dispatchEvent(event);

In the above example, the author only has to set the event object properties that he or she wants. Using legacy initialization methods, such as initMouseEvent(), often requires the author to specify values for numerous additional properties that are not needed.

The following sections define constructors for the interfaces from [DOM3 Events].

2.2 Default values for properties

When an event is created, each attribute on the interface must be initialized to its default value. The default value for an attribute, unless specified otherwise in this specification, is determined by its type:

TypeDefault Value
AbstractViewnull
anynull
booleanfalse
float, long, unsigned long, unsigned short0
DOMStringempty string
DOMTimeStamp0
EventTargetnull

This example creates an instance of the UIEvent interface without specifying a value for the detail attribute. event.detail is initialized to 0 because detail is of type long.

var event = new UIEvent("resize", {view: window});

2.3 UIEvent

// Constructor for UIEvent (introduced in DOM L3 Events)
[Partial]
[Constructor(DOMString type, optional UIEventInit eventInitDict)]
interface UIEvent : Event {
  ...
}

dictionary UIEventInit : EventInit {
  views::AbstractView view;
  long detail;
}
	

2.4 MouseEvent

// Constructor for MouseEvent (introduced in DOM L3 Events)
[Partial]
[Constructor(DOMString type, optional MouseEventInit eventInitDict)]
interface MouseEvent : UIEvent {
  ...
}

dictionary MouseEventInit : UIEventInit {
  long screenX;
  long screenY;
  long clientX;
  long clientY;
  boolean ctrlKey;
  boolean shiftKey;
  boolean altKey;
  boolean metaKey;
  unsigned short button;
  unsigned short buttons;
  EventTarget relatedTarget;
}

2.5 KeyboardEvent

// Constructor for KeyboardEvent (introduced in DOM L3 Events)
[Partial]
[Constructor(DOMString type, optional KeyboardEventInit eventInitDict)]
interface KeyboardEvent : UIEvent {
  ...
}

dictionary KeyboardEventInit : UIEventInit {
  DOMString char;
  DOMString key;
  unsigned long location;
  boolean ctrlKey;
  boolean shiftKey;
  boolean altKey;
  boolean metaKey;
  boolean repeat;
  DOMString locale;
}

2.6 WheelEvent

// Constructor for WheelEvent (introduced in DOM L3 Events)
[Partial]
[Constructor(DOMString type, optional WheelEventInit eventInitDict)]
interface WheelEvent : MouseEvent {
  ...
}

dictionary WheelEventInit : MouseEventInit {
  float deltaX;
  float deltaY;
  float deltaZ;
  unsigned long deltaMode;
}

2.7 TextEvent

// Constructor for TextEvent (introduced in DOM L3 Events)
[Partial]
[Constructor(DOMString type, optional TextEventInit eventInitDict)]
interface TextEvent : UIEvent {
  ...
}

dictionary TextEventInit : UIEventInit {
  DOMString data;
  unsigned long inputMethod;
  DOMString locale;
}

2.8 CompositionEvent

// Constructor for CompositionEvent (introduced in DOM L3 Events)
[Partial]
[Constructor(DOMString type, optional CompositionEventInit eventInitDict)]
interface CompositionEvent : UIEvent {
  ...
}

dictionary CompositionEventInit : UIEventInit {
  DOMString data;
  DOMString locale;
}

2.9 FocusEvent

// Constructor for FocusEvent (introduced in DOM L3 Events)
[Partial]
[Constructor(DOMString type, optional FocusEventInit eventInitDict)]
interface FocusEvent : UIEvent {
  ...
}

dictionary FocusEventInit : UIEventInit {
  EventTarget relatedTarget;
}

Appendix A: References

For the latest version of any W3C specification please consult the list of W3C Technical Reports available at http://www.w3.org/TR.

[DOM3 Core]
Document Object Model Level 3 Core Specification, A. Le Hors, et al., Editors. World Wide Web Consortium, April 2004. URL: http://www.w3.org/TR/DOM-Level-3-Core
[DOM3 Events]
Document Object Model Level 3 Events Specification, D. Schepers, et al. Editors. World Wide Web Consortium, November 2011. URL: http://www.w3.org/TR/DOM-Level-3-Events
[DOM4]
DOM4, A. van Kesteren, et al. Editors. World Wide Web Consortium, September 2011. URL: http://www.w3.org/TR/dom/
[ECMAScript]
ECMAScript Language Specification, Third Edition. European Computer Manufacturers Association, Standard ECMA-262, December 1999. URL: http://www.ecma-international.org/.
[RFC2119]
Key words for use in RFCs to indicate Requirement Levels, S Bradner, 1997. URL: http://rfc.net/rfc2119.html
[Unicode]
The Unicode Standard, Version 5.0, ISBN 0-321-48091-0, as updated periodically by the publication of new versions. URL: http://www.unicode.org/unicode/standard/versions
[HTML5]
HTML 5, I. Hickson, editor. World Wide Web Consortium, work in progress, 25 May 2011. URL: http://www.w3.org/TR/html5/
[WEBIDL]
Web IDL, Cameron McCormack. W3C. URL: http://www.w3.org/TR/WebIDL/