W3C Copyright Notices and Licenses
Copyright © 2008 World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All Rights Reserved.
This document is published under the W3C® Document Copyright Notice and License. The bindings within this document are published under the W3C® Software Copyright Notice and License. The software license requires "Notice of any changes or modifications to the W3C files, including the date changes were made." Consequently, modified versions of the DOM bindings must document that they do not conform to the W3C standard; in the case of the IDL definitions, the pragma prefix can no longer be 'w3c.org'; in the case of the Java language binding, the package names can no longer be in the 'org.w3c' package.
W3C® Document Copyright Notice and License
Note: This section is a copy of the W3C® Document Notice and License and could be found at http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231.
Copyright © 2008 World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All Rights Reserved.
http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231
Public documents on the W3C site are provided by the copyright holders under the following license. By using and/or copying this document, or the W3C document from which this statement is linked, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:
Permission to copy, and distribute the contents of this document, or the W3C document from which this statement is linked, in any medium for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the document, or portions thereof, that you use:
- A link or URL to the original W3C document.
- The pre-existing copyright notice of the original author, or if it doesn't exist, a notice (hypertext is preferred, but a textual representation is permitted) of the form: "Copyright © [$date-of-document] World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All Rights Reserved. http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231"
- If it exists, the STATUS of the W3C document.
When space permits, inclusion of the full text of this NOTICE should be provided. We request that authorship attribution be provided in any software, documents, or other items or products that you create pursuant to the implementation of the contents of this document, or any portion thereof.
No right to create modifications or derivatives of W3C documents is granted pursuant to this license. However, if additional requirements (documented in the Copyright FAQ) are satisfied, the right to create modifications or derivatives is sometimes granted by the W3C to individuals complying with those requirements.
THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.
The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.
W3C® Software Copyright Notice and License
Note: This section is a copy of the W3C® Software Copyright Notice and License and could be found at http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
Copyright © 2008 World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All Rights Reserved.
http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
This work (and included software, documentation such as READMEs, or other related items) is being provided by the copyright holders under the following license. By obtaining, using and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions.
Permission to copy, modify, and distribute this software and its documentation, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the software and documentation or portions thereof, including modifications:
- The full text of this NOTICE in a location viewable to users of the redistributed or derivative work.
- Any pre-existing intellectual property disclaimers, notices, or terms and conditions. If none exist, the W3C® Short Software Notice should be included (hypertext is preferred, text is permitted) within the body of any redistributed or derivative code.
- Notice of any changes or modifications to the files, including the date changes were made. (We recommend you provide URIs to the location from which the code is derived.)
THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the software without specific, written prior permission. Title to copyright in this software and any associated documentation will at all times remain with copyright holders.
1. Document Object Model Events
- Editors:
-
Björn Höhrmann
- Philippe Le Hégaret, W3C (until November 2003)
- Tom Pixley, Netscape Communications Corporation (until July 2002)
1.1 Introduction
DOM Events is designed with two main goals. The first goal is the design of an event system which allows registration of event listeners and describes event flow through a tree structure. Additionally, the specification will provide standard modules of events for user interface control and document mutation notifications, including defined contextual information for each of these event modules.
The second goal of DOM Events is to provide a common subset of the current event systems used in DOM Level 0 browsers. This is intended to foster interoperability of existing scripts and content. It is not expected that this goal will be met with full backwards compatibility. However, the specification attempts to achieve this when possible.
This specification is to be understood in the context of the DOM Level 3 Core specification [
DOM Level 3 Core
] and the general considerations for DOM implementations apply. For example, handling of namespace URIs is discussed in
XML Namespaces
, and behavior in exceptional circumstances (such as when a null argument is passed when null was not expected) is discussed under
DOMException
. For additional information about
conformance
, please see the DOM Level 3 Core specification [
DOM Level 3 Core
].
An implementation is DOM Level 3 Events conformant if it supports the Core module defined in [
DOM Level 2 Core
], the Event dispatch and DOM event flow mechanism and the interfaces with their associated semantics defined in Basic interfaces. An implementation conforms to a DOM Level 3 Events module if it conforms to DOM Level 3 Events, the event types defined in the module, and the modules the module depends upon (if any).
An implementation conforms to an event type if it conforms to its associated semantics and DOM interfaces. This includes that event objects that are generated by the implementation are generated as outlined in the tabular definition of the event type.
An implementation which does not conform to an event module can still implement the DOM interfaces associated with it. The DOM application can then create an event object using the
DocumentEvent.createEvent()
method and dispatch an event type associated with this interface using the
EventTarget.dispatchEvent()
method.
A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "Events" and "3.0" (respectively) to determine whether or not DOM Level 3 Events is supported by the implementation. Since DOM Level 3 Events is built on top of DOM Level 2 Events [
DOM Level 2 Events
], an implementation that returns true for "Events" and "3.0" will also return true for the parameters "Events" and "2.0". The same holds for the feature strings defined for the individual event modules as applicable. Refer to
DOM Features
in [
DOM Level 3 Core
] for additional information.
1.2 Event dispatch and DOM event flow
This section defines the event dispatch mechanism of the event model defined in this specification. Applications may dispatch event objects using the
EventTarget.dispatchEvent()
method, and implementations must dispatch event objects as if through this method. The behavior of this method depends on the event flow associated with the underlying object. An event flow describes how event objects propagate through a data structure. As an example, when an event object is dispatched to an element in an XML document, the object propagates through parts of the document, as determined by the DOM event flow which is defined at the end of this section.
Event objects are always dispatched to an event target called the event's target. At the beginning of the dispatch, implementations must first determine the event object's propagation path. This is an ordered list of event targets the object may propagate to. The last item in the list is the event's target; the preceding items in the list are referred to as the target's ancestors and the immediately preceding item as the target's parent. Once determined, the propagation path cannot be changed. As an example, in the DOM event flow event listeners might change the position of the target node in the document while the event object is being dispatched; such changes do not affect the propagation path.
As the next step the event object accomplishes one or more event phases. This specification defines the following event phases. Event objects accomplish them in the specified order using the partial propagation paths as defined below. A phase is skipped if it is not supported, or if the event object's propagation has been stopped. For example, if the
Event.bubbles
attribute is set to false, the bubble phase is skipped, and if
Event.stopPropagation()
has been called prior to the dispatch, all phases will be skipped.
- The capture phase: the event object propagates through the target's ancestors to the target's parent. This phase is also known as the capturing phase. Event listeners registered for this phase can handle the event before it reaches its target.
- The target phase: the event object has reached the event's target. This phase is also known as the at-target phase. Event listeners registered for this phase can handle the event once it has reached its target.
- The bubble phase: the event object propagates through the target's ancestors in reverse order, starting with the target's parent. This phase is also known as the bubbling phase. Event listeners registered for this phase can handle the event after it has reached its target.
Implementations let event objects accomplish an event phase by applying the following steps while there are pending event targets in the partial propagation path for this phase and the event object's propagation has not been stopped through
Event.stopPropagation()
.
Firstly, the implementation must determine the current target. This is the next pending event target in the partial propagation path, starting with the first. From the perspective of an event listener this is the event target the listener has been registered on.
Secondly, the implementation must determine the current target's candidate event listeners. This is the list of all event listeners that have been registered on the current target in their order of registration. Once determined, the candidate event listeners cannot be changed, adding or removing listeners does not affect the current target's candidate event listeners.
Finally, the implementation must process all candidate event listeners in order and trigger each listener if all the following conditions are met. A listener is triggered by invoking the
EventListener.handleEvent()
method or an equivalent binding-specific mechanism.
- The event object's immediate propagation has not been stopped.
- The listener has been registered for this event phase.
- The listener has been registered for this event type.
As the final step of the event dispatch, for reasons of backwards compatibility, the implementation must reset the event object's internal propagation and default action prevention states. This ensures that an event object may be properly dispatched multiple times while also allowing to prevent the event objects propagation or default actions prior to the event dispatch.
The model defined above applies regardless of the specific event flow associated with an event target. Each event flow defines how the propagation path is determined and which event phases are supported. The DOM event flow is an application of this model: the propagation path for a Node object is determined by its Node.parentNode chain, and all events accomplish the capture and target phases. Whether an event accomplishes the bubble phase is defined individually for each event type. An alternate application of this model can be found in [
DOM Level 3 Load and Save
].
The DOM event model is reentrant. Event listeners may perform actions that cause additional events to be dispatched. Such events are handled in a synchronous manner, the event propagation that causes the event listener to be triggered will resume only after the event dispatch of the new event is completed.
1.3 Default actions and cancelable events
Event objects can have default actions associated with them. These are actions the implementation will perform in combination with the dispatch of the event object, usually after the dispatch has been completed, but in exceptional cases also immediately before the event is dispatched. An example is the [
HTML 4.01
] form element. When the user submits the form (e.g. by pressing on a submit button), the event submit is dispatched to the element and the default action for this event type is generally to send a request to a Web server with the parameters from the form.
Some event objects are cancelable, meaning the default action can be prevented from occuring, or, if the default action is carried out before the dispatch, its effect can be reversed. Whether an event object is cancelable is indicated by the
Event.cancelable
attribute. Event listeners can cancel default actions of cancelable event objects by invoking the
Event.preventDefault()
method, and determine whether an event has been canceled through the
Event.defaultPrevented
attribute while the object is being dispatched, or from the return value of the
EventTarget.dispatchEvent()
method for event objects dispatched by the DOM application itself.
This specification does not offer features to programatically query if an event object has any default action associated to it or associate new ones. It is expected that other specifications define what default actions, if any, are associated with certain event objects. Further, implementations may associate default actions with events as necessary and appropriate. As an example, an implementation may scroll a document view by a certain amount as default action of a mouse wheel event.
1.4 Activation requests and behavior
(This section is currently being rewritten.)
Event targets may have associated activation behavior that implementations perform in response to an activation request. As an example, the typical activiation behavior associated with hyperlinks is to follow the link. Activation requests are typically initiated by users through an input device.
In terms of this specification, the activation behavior of the event target is the default action of the event type DOMActivate. DOM applications should use this event type whenever they wish to make or react to an activation request.
Implementations dispatch the DOMActivate event as default action of a click event. This click event is either part of the activation request (e.g., a user requests activiation using a mouse), or synthesized by the implementation to accomodate legacy applications. Context information of such a click event is implementation dependent.
When implementations dispatch a synthesized click event, the expectation is that they do so as default action of another event type. For example, when a user activates a hyperlink using a keyboard, the click event would be dispatched as default action of the respective keyboard event.
Implementations are required to dispatch the synthesized click event as described above even if they do not dispatch such an event (e.g., when activation is requested by a voice command, since this specification does not address event types for voice input).
Note: The activation of an event target is device dependent but is also application dependent, e.g. a link in a document can be activated using a mouse click or a mouse double click.
1.5 Event types
Each event is associated with a type, called event type. The event type is composed of a local name and a namespace URI as used in [
DOM Level 3 Core
]. All events defined in this specification are in no namespace.
1.5.1 Complete list of event types
Depending on the level of DOM support, or the devices used for display (e.g. screen) or interaction (e.g., mouse, keyboard, touch screen, or voice), these event types can be generated by the implementation. When used with an [
XML 1.0
] or [
HTML 4.01
] application, the specifications of those languages may restrict the semantics and scope (in particular the possible target nodes) associated with an event type. Refer to the specification defining the language used in order to find those restrictions or to find event types that are not defined in this document.
The following table provides a non-normative summary of the event types defined in this specification. All event types are in no namespace and this specification refers to them by their local name only. All events will accomplish the capture and target phases, but not all of them will accomplish the bubbling phase (see also Event dispatch and DOM event flow). Some events are not cancelable (see Default actions and cancelable events). Some events will only be dispatched to a specific set of possible targets in the DOM event flow, specified using node types. Contextual information related to the event type is accessible using DOM interfaces.
| type |
Bubbling phase |
Cancelable |
Target node types |
DOM interface |
|
DOMActivate
|
Yes |
Yes |
Element
|
UIEvent
|
|
DOMFocusIn
|
Yes |
No |
Element
|
UIEvent
|
|
DOMFocusOut
|
Yes |
No |
Element
|
UIEvent
|
|
focus
|
No |
No |
Element
|
UIEvent
|
|
blur
|
No |
No |
Element
|
UIEvent
|
|
textInput
|
Yes |
Yes |
Element
|
TextEvent
|
|
click
|
Yes |
Yes |
Element
|
MouseEvent
|
|
dblclick
|
Yes |
Yes |
Element
|
MouseEvent
|
|
mousedown
|
Yes |
Yes |
Element
|
MouseEvent
|
|
mouseup
|
Yes |
Yes |
Element
|
MouseEvent
|
|
mouseover
|
Yes |
Yes |
Element
|
MouseEvent
|
|
mousemove
|
Yes |
Yes |
Element
|
MouseEvent
|
|
mouseout
|
Yes |
Yes |
Element
|
MouseEvent
|
|
keydown
|
Yes |
Yes |
Element
|
KeyboardEvent
|
|
keyup
|
Yes |
Yes |
Element
|
KeyboardEvent
|
|
wheel
|
Yes |
Yes |
Document, Element |
WheelEvent
|
|
mousewheel
|
Yes |
Yes |
Document, Element |
MouseWheelEvent
|
|
wheel
|
Yes |
Yes |
Document, Element |
WheelEvent
|
|
DOMSubtreeModified
|
Yes |
No |
Document, DocumentFragment, Element, Attr |
MutationEvent
|
|
DOMNodeInserted
|
Yes |
No |
Element, Attr, Text, Comment, CDATASection, DocumentType, EntityReference, ProcessingInstruction |
MutationEvent
|
|
DOMNodeRemoved
|
Yes |
No |
Element, Attr, Text, Comment, CDATASection, DocumentType, EntityReference, ProcessingInstruction |
MutationEvent
|
|
DOMNodeRemovedFromDocument
|
No |
No |
Element, Attr, Text, Comment, CDATASection, DocumentType, EntityReference, ProcessingInstruction |
MutationEvent
|
|
DOMNodeInsertedIntoDocument
|
No |
No |
Element, Attr, Text, Comment, CDATASection, DocumentType, EntityReference, ProcessingInstruction |
MutationEvent
|
|
DOMAttrModified
|
Yes |
No |
Element
|
MutationEvent
|
|
DOMCharacterDataModified
|
Yes |
No |
Text, Comment, CDATASection, ProcessingInstruction |
MutationEvent
|
|
DOMElementNameChanged
|
Yes |
No |
Element
|
MutationNameEvent
|
|
DOMAttributeNameChanged
|
Yes |
No |
Element
|
MutationNameEvent
|
|
load
|
No |
No |
Document, Element |
Event
|
|
unload
|
No |
No |
Document, Element |
Event
|
|
abort
|
Yes |
No |
Element
|
Event
|
|
error
|
Yes |
No |
Element
|
Event
|
|
select
|
Yes |
No |
Element
|
Event
|
|
change
|
Yes |
No |
Element
|
Event
|
|
submit
|
Yes |
Yes |
Element
|
Event
|
|
reset
|
Yes |
Yes |
Element
|
Event
|
|
resize
|
Yes |
No |
Document, Element |
UIEvent
|
|
scroll
|
Yes |
No |
Document, Element |
UIEvent
|
As an example, the event load will trigger event listeners attached on Element nodes for that event and on the capture and target phases. This event cannot be cancelled. If an event listener for the load event is attached to a node other than Document or Element nodes, or if it is attached to the bubbling phase only, this event listener will not be triggered.
The event objects associated with the event types described above may contain context information. Refer to the description of the DOM interfaces for further information.
1.6 Basic interfaces
The interfaces described in this section are fundamental to DOM Level 3 Events and must always be supported by the implementation. Together they define the feature Events 3.0.
- Interface
Event
(introduced in DOM Level 2)
-
The Event interface is used to provide contextual information about an event to the listener processing the event. An object which implements the Event interface is passed as the parameter to an
EventListener
. The object passed to the event listener may also implement derived interfaces that provide access to information directly relating to the type of event they represent.
To create an instance of the Event interface, use the
DocumentEvent.createEvent("Event")
method call.
-
IDL Definition
-
-
Definition group
PhaseType
-
An integer indicating which phase of the event flow is being processed as defined in Event dispatch and DOM event flow.
-
Defined Constants
-
-
AT_TARGET
- The current event is in the target phase, i.e. it is being evaluated at the event target.
-
BUBBLING_PHASE
- The current event phase is the bubbling phase.
-
CAPTURING_PHASE
- The current event phase is the capture phase.
-
Attributes
-
bubbles
of type boolean, readonly- Used to indicate whether or not an event is a bubbling event. If the event can bubble the value is
true, otherwise the value is false.
cancelable
of type boolean, readonly- Used to indicate whether or not an event can have its default action prevented (see also Default actions and cancelable events). If the default action can be prevented the value is
true, otherwise the value is false.
currentTarget
of type
EventTarget
, readonly- Used to indicate the
EventTarget
whose
EventListeners
are currently being processed. This is particularly useful during the capture and bubbling phases. When used with the Event dispatch and DOM event flow, this attribute contains the target node or a target ancestor.
defaultPrevented
of type boolean, readonly, introduced in DOM Level 3- Used to indicate whether
Event.preventDefault()
has been called for this event.
eventPhase
of type unsigned short, readonly- Used to indicate which phase of event flow is currently being accomplished.
namespaceURI
of type DOMString, readonly, introduced in DOM Level 3- The namespace URI associated with this event at initialization time, or
null if it is unspecified.
DOM Level 2 Events initialization methods, such as
Event.initEvent()
, set the value to null.
target
of type
EventTarget
, readonly- Used to indicate the event target. This attribute contains the target node when used with the Event dispatch and DOM event flow.
timeStamp
of type DOMTimeStamp, readonly- Used to specify the time at which the event was created in milliseconds relative to 1970-01-01T00:00:00Z. Due to the fact that some systems may not provide this information the value of
timeStamp may be not available for all events. When not available, the value is 0.
type
of type DOMString, readonly- The local name of the event type. The name must be an NCName as defined in [
XML Namespaces 1.1
] and is case-sensitive.
-
Methods
-
-
initEvent
-
Initializes attributes of an
Event created through the
DocumentEvent.createEvent
method. This method may only be called before the
Event has been dispatched via the
EventTarget.dispatchEvent()
method. If the method is called several times before invoking
EventTarget.dispatchEvent
, only the final invocation takes precedence. This method has no effect if called after the event has been dispatched. If called from a subclass of the
Event interface only the values specified in this method are modified, all other attributes are left unchanged.
This method sets the
Event.type
attribute to
eventTypeArg, and
Event.namespaceURI
to
null. To initialize an event with a namespace URI, use the
Event.initEventNS()
method.
Parameters
eventTypeArg of type DOMString- Specifies
Event.type
, the local name of the event type.
canBubbleArg of type boolean- Specifies
Event.bubbles
. This parameter overrides the intrinsic bubbling behavior of the event.
cancelableArg of type boolean- Specifies
Event.cancelable
. This parameter overrides the intrinsic cancelable behavior of the event.
No Return Value
No Exceptions
initEventNS
introduced in DOM Level 3-
Initializes attributes of an
Event object. This method has the same behavior as
Event.initEvent()
.
Parameters
namespaceURIArg of type DOMString- Specifies
Event.namespaceURI
, the namespace URI associated with this event, or null if no namespace.
eventTypeArg of type DOMString- Refer to the
Event.initEvent()
method for a description of this parameter.
canBubbleArg of type boolean- Refer to the
Event.initEvent()
method for a description of this parameter.
cancelableArg of type boolean- Refer to the
Event.initEvent()
method for a description of this parameter.
No Return Value
No Exceptions
-
preventDefault
-
stopImmediatePropagation
introduced in DOM Level 3-
Prevents other event listeners from being triggered and, unlike
Event.stopPropagation()
its effect is immediate . Once it has been called, further calls to this method have no additional effect.
Note: This method does not prevent the default action from being invoked; use
Event.preventDefault()
for that effect.
No Parameters
No Return Value
No Exceptions
-
stopPropagation
-
Prevents other event listeners from being triggered but its effect is deferred until all event listeners attached on the
Event.currentTarget
have been triggered . Once it has been called, further calls to this method have no additional effect.
Note: This method does not prevent the default action from being invoked; use
Event.preventDefault()
for that effect.
No Parameters
No Return Value
No Exceptions
- Interface
CustomEvent
(introduced in DOM Level 3)
-
The CustomEvent interface is the recommended interface for application-specific event types. Unlike the
Event
interface, it allows applications to provide contextual information about the event type. Application-specific event types should have an associated namespace to avoid clashes with future general-purpose event types.
To create an instance of the CustomEvent interface, use the
DocumentEvent.createEvent("CustomEvent")
method call.
-
IDL Definition
-
// Introduced in DOM Level 3:
interface CustomEvent : Event {
readonly attribute DOMObject detail;
void initCustomEventNS(in DOMString namespaceURIArg,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in DOMObject detailArg);
};
-
Attributes
-
detail
of type DOMObject, readonly- Specifies some detail information about the
Event
.
-
Methods
-
-
initCustomEventNS
-
Initializes attributes of a
CustomEvent object. This method has the same behavior as
Event.initEventNS()
.
Parameters
namespaceURIArg of type DOMString- Refer to the
Event.initEventNS()
method for a description of this parameter.
typeArg of type DOMString- Refer to the
Event.initEventNS()
method for a description of this parameter.
canBubbleArg of type boolean- Refer to the
Event.initEventNS()
method for a description of this parameter.
cancelableArg of type boolean- Refer to the
Event.initEventNS()
method for a description of this parameter.
detailArg of type DOMObject- Specifies
CustomEvent.detail
. This value may be null.
No Return Value
No Exceptions
- Interface
EventTarget
(introduced in DOM Level 2)
-
The EventTarget interface is implemented by all the objects which could be event targets in an implementation which supports an event flow. The interface allows registration and removal of event listeners, and dispatch of events to an event target.
When used with the DOM event flow, this interface is implemented by all target nodes and target ancestors, i.e. all DOM Nodes of the tree support this interface when the implementation conforms to DOM Level 3 Events and, therefore, this interface can be obtained by using binding-specific casting methods on an instance of the Node interface.
Invoking addEventListener or addEventListenerNS repeatedly on the same EventTarget with the same values for the parameters namespaceURI, type, listener, and useCapture has no effect. Doing so does not cause the
EventListener
to be called more than once and does not cause a change in the triggering order.
-
IDL Definition
-
// Introduced in DOM Level 2:
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);
};
-
Methods
-
-
addEventListener
-
Registers an event listener, depending on the
useCapture parameter, on the capture phase of the DOM event flow or its target and bubbling phases. Invoking this method is equivalent to invoking
addEventListenerNS with the same values for the parameters
type,
listener, and
useCapture, and the value
null for the parameter
namespaceURI.
Parameters
type of type DOMString- Specifies the
Event.type
associated with the event for which the user is registering.
listener of type
EventListener
- The
listener parameter takes an object implemented by the user which implements the
EventListener
interface and contains the method to be called when the event occurs.
useCapture of type boolean- If true,
useCapture indicates that the user wishes to add the event listener for the capture phase only, i.e. this event listener will not be triggered during the target and bubbling phases. If false, the event listener will only be triggered during the target and bubbling phases.
No Return Value
No Exceptions
addEventListenerNS
introduced in DOM Level 3-
Registers an event listener, depending on the
useCapture parameter, on the capture phase of the DOM event flow or its target and bubbling phases.
No Return Value
No Exceptions
dispatchEvent
modified in DOM Level 3-
Dispatches an event into the implementation's event model. The
event target of the event is the
EventTarget object on which
dispatchEvent is called.
Parameters
evt of type
Event
- The event to be dispatched.
Exceptions
|
EventException
|
UNSPECIFIED_EVENT_TYPE_ERR: Raised if the
Event.type
was not specified by initializing the event before dispatchEvent was called. Specification of the
Event.type
as null or an empty string will also trigger this exception.
DISPATCH_REQUEST_ERR: Raised if the
Event
object is already being dispatched.
|
|
DOMException
|
NOT_SUPPORTED_ERR: Raised if the
Event
object has not been created using
DocumentEvent.createEvent()
.
INVALID_CHARACTER_ERR: Raised if
Event.type
is not an
NCName
as defined in [
XML Namespaces 1.1
].
|
-
removeEventListener
-
Removes an event listener. Calling
removeEventListener with arguments which do not identify any currently registered
EventListener
on the
EventTarget has no effect. The
Event.namespaceURI
for which the user registered the event listener is implied and is
null.
Parameters
type of type DOMString- Specifies the
Event.type
for which the user registered the event listener.
listener of type
EventListener
- The
EventListener
to be removed.
useCapture of type boolean- Specifies whether the
EventListener
being removed was registered for the capture phase or not. If a listener was registered twice, once for the capture phase and once for the target and bubbling phases, each must be removed separately. Removal of an event listener registered for the capture phase does not affect the same event listener registered for the target and bubbling phases, and vice versa.
No Return Value
No Exceptions
removeEventListenerNS
introduced in DOM Level 3-
Removes an event listener. Calling
removeEventListenerNS with arguments which do not identify any currently registered
EventListener
on the
EventTarget has no effect.
No Return Value
No Exceptions
- Interface
EventListener
(introduced in DOM Level 2)
-
The EventListener interface is the primary way for handling events. Users implement the EventListener interface and register their event listener on an
EventTarget
. The users should also remove their EventListener from its
EventTarget
after they have completed using the listener.
Copying a Node, with methods such as Node.cloneNode or Range.cloneContents, does not copy the event listeners attached to it. Event listeners must be attached to the newly created Node afterwards if so desired.
Moving a Node, with methods Document.adoptNode, Node.appendChild, or Range.extractContents, does not affect the event listeners attached to it.
-
IDL Definition
-
-
Methods
-
-
handleEvent
-
This method is called whenever an event occurs of the event type for which the
EventListener interface was registered.
Parameters
evt of type
Event
- The
Event
contains contextual information about the event.
No Return Value
No Exceptions
- Exception
EventException
introduced in DOM Level 2
-
Event operations may throw an
EventException
as specified in their method descriptions.
-
IDL Definition
-
-
Definition group
EventExceptionCode
-
An integer indicating the type of error generated.
-
Defined Constants
-
-
DISPATCH_REQUEST_ERR
, introduced in DOM Level 3.
- If the
Event
object is already dispatched in the tree.
-
UNSPECIFIED_EVENT_TYPE_ERR
- If the
Event.type
was not specified by initializing the event before the method was called. Specification of the
Event.type
as null or an empty string will also trigger this exception.
1.6.1 Event creation
In most cases, the events dispatched by the DOM Events implementation are also created by the implementation. It is however possible to simulate events such as mouse events by creating the
Event
objects and dispatch them using the DOM Events implementation.
Creating
Event
objects that are known to the DOM Events implementation is done using
DocumentEvent.createEvent()
. The application must then initialize the object by calling the appropriate initialization method before invoking
EventTarget.dispatchEvent()
. The
Event
objects created must be known by the DOM Events implementation; otherwise an event exception is thrown.
- Interface
DocumentEvent
(introduced in DOM Level 2)
-
The DocumentEvent interface provides a mechanism by which the user can create an
Event
object of a type supported by the implementation. If the feature "Events" is supported by the Document object, the DocumentEvent interface must be implemented on the same object. If the feature "+Events" is supported by the Document object, an object that supports the DocumentEvent interface must be returned by invoking the method Node.getFeature("+Events", "3.0") on the Document object.
-
IDL Definition
-
// Introduced in DOM Level 2:
interface DocumentEvent {
Event createEvent(in DOMString eventType)
raises(DOMException);
// Introduced in DOM Level 3:
boolean canDispatch(in DOMString namespaceURI,
in DOMString type);
};
-
Methods
-
canDispatch
introduced in DOM Level 3-
Tests if the implementation can generate events of a specified type.
Return Value
|
boolean
|
true if the implementation can generate and dispatch this event type, false otherwise.
|
No Exceptions
-
createEvent
-
Creates an event object of the type specified.
Parameters
eventType of type DOMString-
The eventType parameter specifies the name of the DOM Events interface to be supported by the created event object, e.g. "Event", "MouseEvent", "MutationEvent" and so on. If the
Event
is to be dispatched via the
EventTarget.dispatchEvent()
method the appropriate event initialization method must be called after creation in order to initialize the
Event
's values.
As an example, a user wishing to synthesize some kind of
UIEvent
would invoke
DocumentEvent.createEvent("UIEvent")
. The
UIEvent.initUIEventNS()
method could then be called on the newly created
UIEvent
object to set the specific type of user interface event to be dispatched, DOMActivate for example, and set its context information, e.g.
UIEvent.detail
in this example.
For backward compatibility reason, "UIEvents", "MouseEvents", "MutationEvents", and "HTMLEvents" feature names are valid values for the parameter eventType and represent respectively the interfaces "UIEvent", "MouseEvent", "MutationEvent", and "Event", and the characters 'a'..'z' are considered equivalent to the characters 'A'..'Z'.
Return Value
|
Event
|
The newly created event object.
|
Exceptions
|
DOMException
|
NOT_SUPPORTED_ERR: Raised if the implementation does not support the
Event
interface requested.
|
1.7 Event module definitions
The DOM Event Model allows a DOM implementation to support multiple modules of events. The model has been designed to allow addition of new event modules if required. The DOM will not attempt to define all possible events. For purposes of interoperability, the DOM defines a module of user interface events including lower level device dependent events and a module of document mutation events.
1.7.1 User Interface event types
This module defines the feature UIEvents 3.0 and depends on the features Events 3.0 and Views 2.0.
The User Interface event module contains basic event types associated with user interfaces.
- Interface
UIEvent
(introduced in DOM Level 2)
-
The UIEvent interface provides specific contextual information associated with User Interface events.
To create an instance of the UIEvent interface, use the
DocumentEvent.createEvent("UIEvent")
method call.
-
IDL Definition
-
// Introduced in DOM Level 2:
interface UIEvent : Event {
readonly attribute views::AbstractView view;
readonly attribute long detail;
void initUIEvent(in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in long detailArg);
// Introduced in DOM Level 3:
void initUIEventNS(in DOMString namespaceURIArg,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in long detailArg);
};
-
Attributes
-
detail
of type long, readonly- Specifies some detail information about the
Event
, depending on the type of event.
view
of type views::AbstractView, readonly- The
view attribute identifies the AbstractView from which the event was generated.
-
Methods
-
-
initUIEvent
-
Initializes attributes of an
UIEvent object. This method has the same behavior as
Event.initEvent()
.
Parameters
typeArg of type DOMString- Refer to the
Event.initEvent()
method for a description of this parameter.
canBubbleArg of type boolean- Refer to the
Event.initEvent()
method for a description of this parameter.
cancelableArg of type boolean- Refer to the
Event.initEvent()
method for a description of this parameter.
viewArg of type views::AbstractView- Specifies
UIEvent.view
. This value may be null.
detailArg of type long- Specifies
UIEvent.detail
.
No Return Value
No Exceptions
initUIEventNS
introduced in DOM Level 3-
Initializes attributes of an
UIEvent object. This method has the same behavior as
Event.initEventNS()
.
Parameters
namespaceURIArg of type DOMString- Refer to the
Event.initEventNS()
method for a description of this parameter.
typeArg of type DOMString- Refer to the
Event.initEventNS()
method for a description of this parameter.
canBubbleArg of type boolean- Refer to the
Event.initEventNS()
method for a description of this parameter.
cancelableArg of type boolean- Refer to the
Event.initEventNS()
method for a description of this parameter.
viewArg of type views::AbstractView- Refer to the
UIEvent.initUIEvent()
method for a description of this parameter.
detailArg of type long- Refer to the
UIEvent.initUIEvent()
method for a description of this parameter.
No Return Value
No Exceptions
The User Interface event types are listed below.
-
DOMFocusIn
-
| Type |
DOMFocusIn
|
| Namespace |
None
|
| Interface |
UIEvent
|
| Cancelable |
No |
| Bubbles |
Yes |
| Target |
Element
|
| Context info |
UIEvent.view
is in use. |
An event target receives focus. The focus is given to the element before the dispatch of this event type. This event type is dispatched after the event type focus.
-
DOMFocusOut
-
| Type |
DOMFocusOut
|
| Namespace |
None
|
| Interface |
UIEvent
|
| Cancelable |
No |
| Bubbles |
Yes |
| Target |
Element
|
| Context info |
UIEvent.view
is in use. |
An event target loses focus. The focus is taken from the element before the dispatch of this event type. This event type is dispatched after the event type blur.
-
focus
-
| Type |
focus
|
| Namespace |
None
|
| Interface |
UIEvent
|
| Cancelable |
No |
| Bubbles |
No |
| Target |
Element
|
| Context info |
UIEvent.view
is in use. |
An event target receives focus. The focus is given to the element before the dispatch of this event type.
-
blur
-
| Type |
blur
|
| Namespace |
None
|
| Interface |
UIEvent
|
| Cancelable |
No |
| Bubbles |
No |
| Target |
Element
|
| Context info |
UIEvent.view
is in use. |
An event target loses focus. The focus is taken from the element before the dispatch of this event type.
1.7.2 Text events types
This module defines the feature TextEvents 3.0 and depends on the feature UIEvents 3.0.
The text event module originates from the [
HTML 4.01
] onkeypress attribute. Unlike this attribute, the event type textInput applies only to characters and is designed for use with any text input devices, not just keyboards. Refer to Appendix A, "Keyboard events and key identifiers", for examples on how text events are used in combination with keyboard events.
- Interface
TextEvent
(introduced in DOM Level 3)
-
The TextEvent interface provides specific contextual information associated with Text Events.
To create an instance of the TextEvent interface, use the
DocumentEvent.createEvent("TextEvent")
method call.
-
IDL Definition
-
// Introduced in DOM Level 3:
interface TextEvent : UIEvent {
readonly attribute DOMString data;
void initTextEvent(in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in DOMString dataArg);
void initTextEventNS(in DOMString namespaceURIArg,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in DOMString dataArg);
};
-
Attributes
-
data
of type DOMString, readonlydata holds the value of the characters generated by the character device. This may be a single Unicode character or a non-empty sequence of Unicode characters [
Unicode
]. Characters should be normalized as defined by the Unicode normalization form NFC, defined in [
UAX #15
]. This attribute cannot be null or contain the empty string.
-
Methods
-
-
initTextEvent
-
Initializes attributes of a
TextEvent object. This method has the same behavior as
UIEvent.initUIEvent()
. The value of
UIEvent.detail
remains undefined.
No Return Value
No Exceptions
-
initTextEventNS
-
Initializes attributes of a
TextEvent object. This method has the same behavior as
UIEvent.initUIEventNS()
. The value of
UIEvent.detail
remains undefined.
No Return Value
No Exceptions
The text event type is listed below.
-
textInput
-
One or more characters have been entered. The characters can originate from a variety of sources. For example, it could be characters resulting from a key being pressed or released on a keyboard device, characters resulting from the processing of an input method editor, or resulting from a voice command. Where a "paste" operation generates a simple sequence of characters, i.e. a text without any structure or style information, this event type should be generated as well.
1.7.3 Keyboard event types
(This part of the specification is likely to be moved to a separate specification on keyboard events.)
This module defines the feature KeyboardEvents 3.0 and depends on the feature UIEvents 3.0.
Keyboard events are device dependent, i.e. they rely on the capabilities of the input devices and how they are mapped in the operating systems. It is therefore highly recommended to rely on Text events types when dealing with character input.
- Interface
KeyboardEvent
(introduced in DOM Level 3)
-
The KeyboardEvent interface provides specific contextual information associated with keyboard devices. Each keyboard event references a key using an identifier. Keyboard events are commonly directed at the element that has the focus.
The KeyboardEvent interface provides convenient attributes for some common modifiers keys:
KeyboardEvent.ctrlKey
,
KeyboardEvent.shiftKey
,
KeyboardEvent.altKey
,
KeyboardEvent.metaKey
. These attributes are equivalent to using the method
KeyboardEvent.getModifierState(keyIdentifierArg)
with "Control", "Shift", "Alt", or "Meta" respectively.
To create an instance of the KeyboardEvent interface, use the
DocumentEvent.createEvent("KeyboardEvent")
method call.
-
IDL Definition
-
// Introduced in DOM Level 3:
interface KeyboardEvent : UIEvent {
// KeyLocationCode
const unsigned long DOM_KEY_LOCATION_STANDARD = 0x00;
const unsigned long DOM_KEY_LOCATION_LEFT = 0x01;
const unsigned long DOM_KEY_LOCATION_RIGHT = 0x02;
const unsigned long DOM_KEY_LOCATION_NUMPAD = 0x03;
readonly attribute DOMString keyIdentifier;
readonly attribute unsigned long keyLocation;
readonly attribute boolean ctrlKey;
readonly attribute boolean shiftKey;
readonly attribute boolean altKey;
readonly attribute boolean metaKey;
boolean getModifierState(in DOMString keyIdentifierArg);
void initKeyboardEvent(in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in DOMString keyIdentifierArg,
in unsigned long keyLocationArg,
in DOMString modifiersListArg);
void initKeyboardEventNS(in DOMString namespaceURIArg,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in DOMString keyIdentifierArg,
in unsigned long keyLocationArg,
in DOMString modifiersListArg);
};
-
Definition group
KeyLocationCode
-
This set of constants is used to indicate the location of a key on the device. In case a DOM implementation wishes to provide a new location information, a value different from the following constant values must be used.
-
Defined Constants
-
-
DOM_KEY_LOCATION_LEFT
- The key activated is in the left key location (there is more than one possible location for this key). Example: the left Shift key on a PC 101 Key US keyboard.
-
DOM_KEY_LOCATION_NUMPAD
- The key activation originated on the numeric keypad or with a virtual key corresponding to the numeric keypad. Example: the '1' key on a PC 101 Key US keyboard located on the numeric pad.
-
DOM_KEY_LOCATION_RIGHT
- The key activation is in the right key location (there is more than one possible location for this key). Example: the right Shift key on a PC 101 Key US keyboard.
-
DOM_KEY_LOCATION_STANDARD
- The key activation is not distinguished as the left or right version of the key, and did not originate from the numeric keypad (or did not originate with a virtual key corresponding to the numeric keypad). Example: the 'Q' key on a PC 101 Key US keyboard.
-
Attributes
-
altKey
of type boolean, readonlytrue if the alternative (Alt) key modifier is activated.
Note: The Option key modifier on Macintosh systems must be represented using this key modifier.
ctrlKey
of type boolean, readonlytrue if the control (Ctrl) key modifier is activated.
keyIdentifier
of type DOMString, readonlykeyIdentifier holds the identifier of the key. The key identifiers are defined in Appendix A.2 "Key identifiers set". Implementations that are unable to identify a key must use the key identifier "Unidentified".
keyLocation
of type unsigned long, readonly- The
keyLocation attribute contains an indication of the location of they key on the device, as described in Keyboard event types.
metaKey
of type boolean, readonlytrue if the meta (Meta) key modifier is activated.
Note: The Command key modifier on Macintosh systems must be represented using this key modifier.
shiftKey
of type boolean, readonlytrue if the shift (Shift) key modifier is activated.
-
Methods
-
-
getModifierState
-
Queries the state of a modifier using a key identifier. See also
Modifier keys.
Parameters
keyIdentifierArg of type DOMString- A modifier key identifier. Common modifier keys are
"Alt", "AltGraph", "CapsLock", "Control", "Meta", "NumLock", "Scroll", or "Shift".
Note: If an application wishes to distinguish between right and left modifiers, this information could be deduced using keyboard events and
KeyboardEvent.keyLocation
.
Return Value
|
boolean
|
true if it is a modifier key and the modifier is activated, false otherwise.
|
No Exceptions
-
initKeyboardEvent
-
Initializes attributes of a
KeyboardEvent object. This method has the same behavior as
UIEvent.initUIEvent()
. The value of
UIEvent.detail
remains undefined.
Parameters
typeArg of type DOMString- Refer to the
UIEvent.initUIEvent()
method for a description of this parameter.
canBubbleArg of type boolean- Refer to the
UIEvent.initUIEvent()
method for a description of this parameter.
cancelableArg of type boolean- Refer to the
UIEvent.initUIEvent()
method for a description of this parameter.
viewArg of type views::AbstractView- Refer to the
UIEvent.initUIEvent()
method for a description of this parameter.
keyIdentifierArg of type DOMString- Specifies
KeyboardEvent.keyIdentifier
.
keyLocationArg of type unsigned long- Specifies
KeyboardEvent.keyLocation
.
modifiersListArg of type DOMString- A
white space
separated list of modifier key identifiers to be activated on this object. As an example,
"Control Alt" will mark the control and alt modifiers as activated.
No Return Value
No Exceptions
-
initKeyboardEventNS
-
Initializes attributes of a
KeyboardEvent object. This method has the same behavior as
UIEvent.initUIEventNS()
. The value of
UIEvent.detail
remains undefined.
No Return Value
No Exceptions
Depending on the character generation device, keyboard events may or may not be generated.
The keyboard event types are listed below.
-
keydown
-
A key is pressed down. This event type is device dependent and relies on the capabilities of the input devices and how they are mapped in the operating system. This event type is generated after the keyboard mapping but before the processing of an input method editor. This event should logically happen before the event keyup is produced. Whether a keydown contributes or not to the generation of a text event is implementation dependent.
-
keyup
-
A key is released. This event type is device dependent and relies on the capabilities of the input devices and how they are mapped in the operating system. This event type is generated after the keyboard mapping but before the processing of an input method editor. This event should logically happen after the event keydown is produced. Whether a keyup contributes or not to the generation of a text event is implementation dependent.
1.7.4 Mouse event types
This module defines the feature MouseEvents 3.0 and depends on the feature UIEvents 3.0.
The Mouse event module originates from the [
HTML 4.01
] onclick, ondblclick, onmousedown, onmouseup, onmouseover, onmousemove, and onmouseout attributes. This event module is specifically designed for use with pointing input devices, such as a mouse or a trackball.
- Interface
MouseEvent
(introduced in DOM Level 2)
-
The MouseEvent interface provides specific contextual information associated with Mouse events.
In the case of nested elements mouse events are always targeted at the most deeply nested element. Ancestors of the targeted element may use bubbling to obtain notification of mouse events which occur within their descendent elements.
To create an instance of the MouseEvent interface, use the
DocumentEvent.createEvent("MouseEvent")
method call.
Note: When initializing MouseEvent objects using initMouseEvent or initMouseEventNS, implementations should use the client coordinates clientX and clientY for calculation of other coordinates (such as target coordinates exposed by DOM Level 0 implementations).
-
IDL Definition
-
// Introduced in DOM Level 2:
interface MouseEvent : UIEvent {
readonly attribute long screenX;
readonly attribute long screenY;
readonly attribute long clientX;
readonly attribute long clientY;
readonly attribute boolean ctrlKey;
readonly attribute boolean shiftKey;
readonly attribute boolean altKey;
readonly attribute boolean metaKey;
readonly attribute unsigned short button;
readonly attribute EventTarget relatedTarget;
void initMouseEvent(in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in long detailArg,
in long screenXArg,
in long screenYArg,
in long clientXArg,
in long clientYArg,
in boolean ctrlKeyArg,
in boolean altKeyArg,
in boolean shiftKeyArg,
in boolean metaKeyArg,
in unsigned short buttonArg,
in EventTarget relatedTargetArg);
// Introduced in DOM Level 3:
boolean getModifierState(in DOMString keyIdentifierArg);
// Introduced in DOM Level 3:
void initMouseEventNS(in DOMString namespaceURIArg,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in long detailArg,
in long screenXArg,
in long screenYArg,
in long clientXArg,
in long clientYArg,
in unsigned short buttonArg,
in EventTarget relatedTargetArg,
in DOMString modifiersListArg);
};
-
Attributes
-
altKey
of type boolean, readonly- Refer to the
KeyboardEvent.altKey
attribute.
button
of type unsigned short, readonly- During mouse events caused by the depression or release of a mouse button,
button is used to indicate which mouse button changed state. 0 indicates the normal button of the mouse (in general on the left or the one button on Macintosh mice, used to activate a button or select text). 2 indicates the contextual property (in general on the right, used to display a context menu) button of the mouse if present. 1 indicates the extra (in general in the middle and often combined with the mouse wheel) button. Some mice may provide or simulate more buttons, and values higher than 2 can be used to represent such buttons.
clientX
of type long, readonly- The horizontal coordinate at which the event occurred relative to the viewport associated with the event.
clientY
of type long, readonly- The vertical coordinate at which the event occurred relative to the viewport associated with the event.
ctrlKey
of type boolean, readonly- Refer to the
KeyboardEvent.ctrlKey
attribute.
metaKey
of type boolean, readonly- Refer to the
KeyboardEvent.metaKey
attribute.
relatedTarget
of type
EventTarget
, readonly- Used to identify a secondary
EventTarget
related to a UI event, depending on the type of event.
screenX
of type long, readonly- The horizontal coordinate at which the event occurred relative to the origin of the screen coordinate system.
screenY
of type long, readonly- The vertical coordinate at which the event occurred relative to the origin of the screen coordinate system.
shiftKey
of type boolean, readonly- Refer to the
KeyboardEvent.shiftKey
attribute.
-
Methods
-
getModifierState
introduced in DOM Level 3-
Queries the state of a modifier using a key identifier. See also
Modifier keys.
Return Value
|
boolean
|
true if it is a modifier key and the modifier is activated, false otherwise.
|
No Exceptions
-
initMouseEvent
-
Initializes attributes of a
MouseEvent object. This method has the same behavior as
UIEvent.initUIEvent()
.
No Return Value
No Exceptions
initMouseEventNS
introduced in DOM Level 3-
Initializes attributes of a
MouseEvent object. This method has the same behavior as
UIEvent.initUIEventNS()
.
No Return Value
No Exceptions
The Mouse event types are listed below. In the case of nested elements, mouse event types are always targeted at the most deeply nested element. Ancestors of the targeted element may use bubbling to obtain notification of mouse events which occur within its descendent elements.
Implementations must maintain the current click count when generating mouse events. This is a non-negative integer indicating the number of consecutive clicks of a pointing device button during a user action. The notion of consecutive clicks depends on the environment configuration. For example, a "double click" might not happen if there is a long delay between the two clicks.
-
click
-
A pointing device button is clicked over an element. The definition of a click depends on the environment configuration; i.e. it may depend on the screen location or the delay between the press and release of the pointing device button. In any case, the event target must be the same between the mousedown, mouseup, and click. The sequence of these events is: mousedown, mouseup, and click. It depends on the environment configuration whether the event type click can occur if one or more of the event types mouseover, mousemove, and mouseout occur between the press and release of the pointing device button. In addition, the event type is dispatched as described in Activation requests and behavior.
-
dblclick
-
A pointing device button is clicked twice over an element. The definition of a double click depends on the environment configuration, except that the event target must be the same between mousedown, mouseup, and dblclick. This event type is dispatched after the event type click if a click and double click occur simultaneously, and after the event type mouseup otherwise.
-
mousedown
-
| Type |
mousedown
|
| Namespace |
None
|
| Interface |
MouseEvent
|
| Cancelable |
Yes |
| Bubbles |
Yes |
| Target |
Element
|
| Context info |
MouseEvent.screenX
,
MouseEvent.screenY
,
MouseEvent.clientX
,
MouseEvent.clientY
,
MouseEvent.altKey
,
MouseEvent.ctrlKey
,
MouseEvent.shiftKey
,
MouseEvent.metaKey
,
MouseEvent.button
, and
UIEvent.view
are in use. The
UIEvent.detail
attribute indicates the current click count incremented by one. For example, if no click happened before the mousedown,
UIEvent.detail
will contain the value 1. |
A pointing device button is pressed over an element.
-
mouseup
-
A pointing device button is released over an element.
-
mouseover
-
A pointing device is moved onto an element.
-
mousemove
-
A pointing device is moved while it is over an element.
-
mouseout
-
A pointing device is moved away from an element.
1.7.5 Mouse wheel event types
This module defines the feature MouseWheelEvents 3.0 and depends on the feature MouseEvents 3.0.
Mouse wheel events are included for specification of legacy support, but are deprecated. Authors are encouraged to use Wheel event types instead.
- Interface
MouseWheelEvent
(introduced in DOM Level 3)
-
The MouseWheelEvent interface provides specific contextual information associated with mouse wheel events.
To create an instance of the MouseWheelEvent interface, use the
DocumentEvent.createEvent("MouseWheelEvent")
method call.
-
IDL Definition
-
// Introduced in DOM Level 3:
interface MouseWheelEvent : MouseEvent {
readonly attribute long wheelDelta;
void initMouseWheelEventNS(in DOMString namespaceURIArg,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in long detailArg,
in long screenXArg,
in long screenYArg,
in long clientXArg,
in long clientYArg,
in unsigned short buttonArg,
in EventTarget relatedTargetArg,
in DOMString modifiersListArg,
in long wheelDeltaArg);
};
-
Attributes
-
wheelDelta
of type long, readonly- The distance the wheel has rotated around the y-axis.
-
Methods
-
-
initMouseWheelEventNS
-
Initializes attributes of a
MouseWheelEvent object. This method has the same behavior as
MouseEvent.initMouseEventNS()
.
No Return Value
No Exceptions
-
mousewheel
-
| Type |
mousewheel
|
| Namespace |
None
|
| Interface |
MouseWheelEvent
|
| Cancelable |
Yes |
| Bubbles |
Yes |
| Target |
Document, Element |
| Context info |
MouseWheelEvent.wheelDelta
,
MouseEvent.altKey
,
MouseEvent.ctrlKey
,
MouseEvent.shiftKey
,
MouseEvent.metaKey
, and
UIEvent.view
are in use.
MouseEvent.screenX
,
MouseEvent.screenY
,
MouseEvent.clientX
,
MouseEvent.clientY
, and
MouseEvent.button
are in use if the wheel is associated to a pointing device.
MouseEvent.relatedTarget
indicates the event target the pointing device is pointing at, if any.
UIEvent.detail
is not in use. |
A mouse wheel has been rotated around the y-axis.
1.7.6 Wheel event types
This module defines the feature WheelEvents 3.0 and depends on the feature MouseEvents 3.0.
Wheels are devices that can be rotated in one or more spatial dimensions, and which may or may not be associated with a pointer device. The coordinate system depends on the environment configuration. As an example, the environment may be configured to associate vertical scrolling with rotation along the y-axis, horizontal scrolling with rotation along the x-axis, and zooming with rotation along the z-axis. The deltax, deltaY, and deltaX attributes of
WheelEvent
objects indicate the distance of the rotation, as specified in the delta definition.
-
delta
-
The distance the wheel has rotated around the its axis.
The value of a delta is a integer indicating a distance, measured as the number of rolls the wheel has been rotated. A positive value shall indicate that the wheel has been rotated away from the user on vertically-aligned devices or in a left-hand manner on horizontally aligned devices, and a negative value shall indicate that the wheel has been rotated towards the user on vertically-aligned devices or in a right-hand manner on horizontally-aligned devices. The default value of a delta attribute shall be 0.
-
roll
- A unit of rotation for a device using the WheelEvent interface. On some devices this is a finite physical step. On devices with smooth rotation, a roll becomes the smallest reported amount of rotation.
-
rotation
- An indication of incremental change. On some devices this is a literal rotation of a wheel, while on others, it may be
movement along a flat surface, or pressure on a particular button.
Should we include some additional attribute that denotes what units the roll is in, such as pixels or lines? See ISSUE-9.
- Interface
WheelEvent
(introduced in DOM Level 3)
-
The WheelEvent interface provides specific contextual information associated with omnidirectional mouse wheel events.
To create an instance of the WheelEvent interface, use the
DocumentEvent.createEvent("WheelEvent")
method call.
-
IDL Definition
-
// Introduced in DOM Level 3:
interface WheelEvent : MouseEvent {
readonly attribute long deltaX;
readonly attribute long deltaY;
readonly attribute long deltaZ;
void initWheelEventNS(in DOMString namespaceURIArg,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in long detailArg,
in long screenXArg,
in long screenYArg,
in long clientXArg,
in long clientYArg,
in unsigned short buttonArg,
in EventTarget relatedTargetArg,
in DOMString modifiersListArg,
in long deltaXArg,
in long deltaYArg,
in long deltaZArg);
};
-
Attributes
-
deltaX
of type long, readonly- The distance the wheel has rotated around the x-axis.
deltaY
of type long, readonly- The distance the wheel has rotated around the y-axis.
deltaZ
of type long, readonly- The distance the wheel has rotated around the z-axis.
-
Methods
-
-
initWheelEventNS
-
Initializes attributes of a
WheelEvent object. This method has the same behavior as
MouseEvent.initMouseEventNS()
.
No Return Value
No Exceptions
-
wheel
-
| Type |
wheel
|
| Namespace |
None
|
| Interface |
WheelEvent
|
| Cancelable |
Yes |
| Bubbles |
Yes |
| Target |
Document, Element |
| Context info |
WheelEvent.deltaX
,
WheelEvent.deltaY
,
WheelEvent.deltaZ
,
MouseEvent.altKey
,
MouseEvent.ctrlKey
,
MouseEvent.shiftKey
,
MouseEvent.metaKey
, and
UIEvent.view
are in use.
MouseEvent.screenX
,
MouseEvent.screenY
,
MouseEvent.clientX
,
MouseEvent.clientY
, and
MouseEvent.button
are in use if the wheel is associated to a pointing device.
MouseEvent.relatedTarget
indicates the event target the pointing device is pointing at, if any.
UIEvent.detail
is not in use. |
A mouse wheel has been rotated. A default action of user agent generated event objects of this type causes implementations to dispatch a mousewheel event iff it supports that event type and
WheelEvent.deltaY
is non-zero.
1.7.7 Mutation event types
This module defines the feature MutationEvents 3.0 and depends on the feature Events 3.0.
The mutation and mutation name event modules are designed to allow notification of any changes to the structure of a document, including attribute, text, or name modifications. It may be noted that none of the event types associated with the modules are designated as cancelable. This stems from the fact that it is very difficult to make use of existing DOM interfaces which cause document modifications if any change to the document might or might not take place due to cancelation of the resulting event. Although this is still a desired capability, it was decided that it would be better left until the addition of transactions into the DOM.
Many single modifications of the tree can cause multiple mutation events to be dispatched. Rather than attempt to specify the ordering of mutation events due to every possible modification of the tree, the ordering of these events is left to the implementation.
- Interface
MutationEvent
(introduced in DOM Level 2)
-
The MutationEvent interface provides specific contextual information associated with Mutation events.
To create an instance of the MutationEvent interface, use the
DocumentEvent.createEvent("MutationEvent")
method call.
-
IDL Definition
-
// Introduced in DOM Level 2:
interface MutationEvent : Event {
// attrChangeType
const unsigned short MODIFICATION = 1;
const unsigned short ADDITION = 2;
const unsigned short REMOVAL = 3;
readonly attribute Node relatedNode;
readonly attribute DOMString prevValue;
readonly attribute DOMString newValue;
readonly attribute DOMString attrName;
readonly attribute unsigned short attrChange;
void initMutationEvent(in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in Node relatedNodeArg,
in DOMString prevValueArg,
in DOMString newValueArg,
in DOMString attrNameArg,
in unsigned short attrChangeArg);
// Introduced in DOM Level 3:
void initMutationEventNS(in DOMString namespaceURIArg,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in Node relatedNodeArg,
in DOMString prevValueArg,
in DOMString newValueArg,
in DOMString attrNameArg,
in unsigned short attrChangeArg);
};
-
Definition group
attrChangeType
-
An integer indicating in which way the Attr was changed.
-
Defined Constants
-
-
ADDITION
- The
Attr was just added.
-
MODIFICATION
- The
Attr was modified in place.
-
REMOVAL
- The
Attr was just removed.
-
Attributes
-
attrChange
of type unsigned short, readonlyattrChange indicates the type of change which triggered the DOMAttrModified event. The values can be MODIFICATION, ADDITION, or REMOVAL.
attrName
of type DOMString, readonlyattrName indicates the name of the changed Attr node in a DOMAttrModified event.
newValue
of type DOMString, readonlynewValue indicates the new value of the Attr node in DOMAttrModified events, and of the CharacterData node in DOMCharacterDataModified events.
prevValue
of type DOMString, readonlyprevValue indicates the previous value of the Attr node in DOMAttrModified events, and of the CharacterData node in DOMCharacterDataModified events.
relatedNode
of type Node, readonlyrelatedNode is used to identify a secondary node related to a mutation event. For example, if a mutation event is dispatched to a node indicating that its parent has changed, the relatedNode is the changed parent. If an event is instead dispatched to a subtree indicating a node was changed within it, the relatedNode is the changed node. In the case of the DOMAttrModified event it indicates the Attr node which was modified, added, or removed.
-
Methods
-
-
initMutationEvent
-
Initializes attributes of a
MutationEvent object. This method has the same behavior as
Event.initEvent()
.
No Return Value
No Exceptions
initMutationEventNS
introduced in DOM Level 3-
Initializes attributes of a
MutationEvent object. This method has the same behavior as
Event.initEventNS()
.
No Return Value
No Exceptions
The mutation event types are listed below.
-
DOMSubtreeModified
-
| Type |
DOMSubtreeModified
|
| Namespace |
None
|
| Interface |
MutationEvent
|
| Cancelable |
No |
| Bubbles |
Yes |
| Target |
Document, DocumentFragment, Element, Attr |
| Context info |
None |
This is a general event for notification of all changes to the document. It can be used instead of the more specific mutation and mutation name events listed below. It may be dispatched after a single modification to the document or, at the implementation's discretion, after multiple changes have occurred. The latter use should generally be used to accommodate multiple changes which occur either simultaneously or in rapid succession. The target of this event is the lowest common parent of the changes which have taken place. This event is dispatched after any other events caused by the mutation(s) have occurred.
-
DOMNodeInserted
-
| Type |
DOMNodeInserted
|
| Namespace |
None
|
| Interface |
MutationEvent
|
| Cancelable |
No |
| Bubbles |
Yes |
| Target |
Element, Attr, Text, Comment, CDATASection, DocumentType, EntityReference, ProcessingInstruction |
| Context info |
MutationEvent.relatedNode
holds the parent node of the node that has been inserted or, in case of Attr nodes, the ownerElement of the Attr node. |
A node has been added as a child of another node or, in case of Attr nodes, has been added to an Element. This event is dispatched after the insertion has taken place. The target node of this event is the node being inserted.
-
DOMNodeRemoved
-
| Type |
DOMNodeRemoved
|
| Namespace |
None
|
| Interface |
MutationEvent
|
| Cancelable |
No |
| Bubbles |
Yes |
| Target |
Element, Attr, Text, Comment, CDATASection, DocumentType, EntityReference, ProcessingInstruction |
| Context info |
MutationEvent.relatedNode
holds the parent node of the node being removed or, in case of Attr nodes, the ownerElement of the Attr node. |
A node is being removed from its parent node or, in case of Attr nodes, removed from its ownerElement. This event is dispatched before the removal takes place. The target node of this event is the node being removed.
-
DOMNodeRemovedFromDocument
-
| Type |
DOMNodeRemovedFromDocument
|
| Namespace |
None
|
| Interface |
MutationEvent
|
| Cancelable |
No |
| Bubbles |
No |
| Target |
Element, Attr, Text, Comment, CDATASection, DocumentType, EntityReference, ProcessingInstruction |
| Context info |
None |
A node is being removed from a document, either through direct removal of the node or removal of a subtree in which it is contained; Attr nodes are considered part of an Element's subtree. This event is dispatched before the removal takes place. The target node of this event type is the node being removed. If the node is being directly removed, the event type DOMNodeRemoved occurs before this event type.
-
DOMNodeInsertedIntoDocument
-
| Type |
DOMNodeInsertedIntoDocument
|
| Namespace |
None
|
| Interface |
MutationEvent
|
| Cancelable |
No |
| Bubbles |
No |
| Target |
Element, Attr, Text, Comment, CDATASection, DocumentType, EntityReference, ProcessingInstruction |
| Context info |
None |
A node has been inserted into a document, either through direct insertion of the node or insertion of a subtree in which it is contained; Attr nodes are considered part of an Element's subtree. This event is dispatched after the insertion has taken place. The target node of this event is the node being inserted. If the node is being directly inserted, the event type DOMNodeInserted occurs before this event type.
-
DOMAttrModified
-
Occurs after
Attr.value has been modified and after an Attr node has been added to or removed from an Element. The target node of this event is the Element node where the change occured. It is implementation dependent whether this event type occurs when the children of the Attr node are changed in ways that do not affect the value of Attr.value.
-
DOMCharacterDataModified
-
Occurs after
CharacterData.data or ProcessingInstruction.data have been modified but the node itself has not been inserted or deleted. The target node of this event is the CharacterData node or the ProcessingInstruction node.
1.7.8 Mutation name event types
This module defines the feature MutationNameEvents 3.0 and depends on the features MutationEvents 3.0 and Core 3.0.
- Interface
MutationNameEvent
(introduced in DOM Level 3)
-
The MutationNameEvent interface provides specific contextual information associated with Mutation name event types.
To create an instance of the MutationNameEvent interface, use the Document.createEvent("MutationNameEvent") method call.
-
IDL Definition
-
// Introduced in DOM Level 3:
interface MutationNameEvent : MutationEvent {
readonly attribute DOMString prevNamespaceURI;
readonly attribute DOMString prevNodeName;
// Introduced in DOM Level 3:
void initMutationNameEvent(in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in Node relatedNodeArg,
in DOMString prevNamespaceURIArg,
in DOMString prevNodeNameArg);
// Introduced in DOM Level 3:
void initMutationNameEventNS(in DOMString namespaceURIArg,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in Node relatedNodeArg,
in DOMString prevNamespaceURIArg,
in DOMString prevNodeNameArg);
};
-
Attributes
-
prevNamespaceURI
of type DOMString, readonly- The previous value of the
relatedNode's namespaceURI.
prevNodeName
of type DOMString, readonly- The previous value of the
relatedNode's nodeName.
-
Methods
-
initMutationNameEvent
introduced in DOM Level 3-
initMutationNameEventNS
introduced in DOM Level 3-
The mutation name event types are listed below.
-
DOMElementNameChanged
-
Occurs after the
namespaceURI and/or the nodeName of an Element node have been modified (e.g., the element was renamed using Document.renameNode()). The target node of this event is the renamed Element node.
-
DOMAttributeNameChanged
-
Occurs after the
namespaceURI and/or the nodeName of a Attr node have been modified (e.g., the attribute was renamed using Document.renameNode()). The target node of this event is the Element node whose Attr has been renamed.
1.7.9 Basic event types
This event module contains basic event types associated with document manipulation. It defines the feature BasicEvents 3.0 and depends on the feature Events 3.0. The basic event types are listed below.
-
load
-
| Type |
load
|
| Namespace |
None
|
| Interface |
UIEvent
if generated from a user interface,
Event
otherwise. |
| Cancelable |
No |
| Bubbles |
No |
| Target |
Document, Element |
| Context info |
UIEvent.view
may be in use. |
The DOM Implementation finishes loading the resource (such as the document) and any dependent resources (such as images, style sheets, or scripts). Dependent resources that fail to load will not prevent this event from firing if the resource that loaded them is still accessible via the DOM. If this event type is dispatched, implementations are required to dispatch this event at least on the Document node.
-
unload
-
| Type |
unload
|
| Namespace |
None
|
| Interface |
UIEvent
if generated from a user interface,
Event
otherwise. |
| Cancelable |
No |
| Bubbles |
No |
| Target |
Document, Element |
| Context info |
UIEvent.view
may be in use. |
The DOM implementation removes from the environment the resource (such as the document) or any dependent resources (such as images, style sheets, scripts). The document is unloaded after the dispatch of this event type. If this event type is dispatched, implementations are required to dispatch this event at least on the Document node.
-
abort
-
| Type |
abort
|
| Namespace |
None
|
| Interface |
UIEvent
if generated from a user interface,
Event
otherwise. |
| Cancelable |
No |
| Bubbles |
Yes |
| Target |
Element
|
| Context info |
UIEvent.view
may be in use. |
Loading of a resource has been aborted.
-
error
-
| Type |
error
|
| Namespace |
None
|
| Interface |
UIEvent
if generated from a user interface,
Event
otherwise. |
| Cancelable |
No |
| Bubbles |
Yes |
| Target |
Element
|
| Context info |
UIEvent.view
may be in use. |
A resource failed to load, or has been loaded but cannot be interpreted according to its semantics such as an invalid image, a script execution error, or non-well-formed XML.
-
select
-
| Type |
select
|
| Namespace |
None
|
| Interface |
UIEvent
if generated from a user interface,
Event
otherwise. |
| Cancelable |
No |
| Bubbles |
Yes |
| Target |
Element
|
| Context info |
UIEvent.view
may be in use. |
A user selects some text. DOM Level 3 Events does not provide contextual information to access the selected text. The selection occured before the dispatch of this event type.
-
change
-
| Type |
change
|
| Namespace |
None
|
| Interface |
UIEvent
if generated from a user interface,
Event
otherwise. |
| Cancelable |
No |
| Bubbles |
Yes |
| Target |
Element
|
| Context info |
UIEvent.view
may be in use. |
A control loses the input focus and its value has been modified since gaining focus. This event type is dispatched before the event type blur.
-
submit
-
| Type |
submit
|
| Namespace |
None
|
| Interface |
UIEvent
if generated from a user interface,
Event
otherwise. |
| Cancelable |
Yes |
| Bubbles |
Yes |
| Target |
Element
|
| Context info |
UIEvent.view
may be in use. |
A form, such as a [
HTML 4.01
] or [
XHTML 1.0
] form, is submitted.
-
reset
-
| Type |
reset
|
| Namespace |
None
|
| Interface |
UIEvent
if generated from a user interface,
Event
otherwise. |
| Cancelable |
Yes |
| Bubbles |
Yes |
| Target |
Element
|
| Context info |
UIEvent.view
may be in use. |
A form, such as a [
HTML 4.01
] or [
XHTML 1.0
] form, is reset.
-
resize
-
| Type |
resize
|
| Namespace |
None
|
| Interface |
UIEvent
|
| Cancelable |
No |
| Bubbles |
Yes |
| Target |
Document, Element |
| Context info |
UIEvent.view
is in use. |
A document view or an element has been resized. The resize occured before the dispatch of this event type.
-
scroll
-
| Type |
scroll
|
| Namespace |
None
|
| Interface |
UIEvent
|
| Cancelable |
No |
| Bubbles |
Yes |
| Target |
Document, Element |
| Context info |
UIEvent.view
is in use. |
A document view or an element has been scrolled. The scroll occured before the dispatch of this event type.
Appendix A: Keyboard events and key identifiers
- Editors:
-
Björn Höhrmann
- Philippe Le Hégaret, W3C (until November 2003)
(This part of the specification is likely to be moved to a separate specification on keyboard events.)
This section contains necessary information regarding keyboard events:
- Relations between keys, such as dead keys or modifiers keys.
- Relations between keyboard events, their default actions, and text events.
- The set of key identifiers, and guidelines on how to extend this set.
Note: This section uses serbian and kanji characters which are not always available (or are misrepresented) in the alternative versions or printed versions of this specification.
A.1 Introduction
Each keyboard event references a key using a DOMString key identifier. The set contained in this appendix is based on the sets of keycodes from:
While implementations are recommended to use the most relevant identifier for a key independently of the platform or keyboard layout mappings, DOM applications should not make assumption on the ability of keyboard devices to generate them. When using keyboard events, "consider using numbers and function keys (F4, F5, and so on) instead of letters in shortcut-key combinations" ([
DWW95
]) given that most keyboard layouts will provide keys for those.
"U+0000", "U+0001", ..., "U+10FFFF" are Unicode based key identifiers ([
Unicode
]). When a key cannot be mapped to Unicode, a specific identifier is used (see also Guidelines for defining key identifiers). In any case, no assumption should be made between the sequence of keyboard events and the text events. The following three examples illustrate the concept of keyboard layout mappings and its relation with keyboard events (following the Guidelines for defining key identifiers, the 'Q' key is mapped to the Latin Capital Letter Q key).
The keystroke "U+0051" (Latin Capital Letter Q key) will produce (on a PC/AT US keyboard using a US keyboard layout mapping and without any modifier activated) the Unicode character q (Latin Small Letter Q):
"keydown": "U+0051" (Latin Capital Letter Q key)"textInput": "q""keyup": "U+0051"
If the keyboard layout mapping is switched to a french mapping, pressing the same key will produce:
"keydown": "U+0041" (Latin Capital Letter A key)"textInput": "a""keyup": "U+0041"
If the keyboard layout mapping is switched to a serbian (cyrillic) mapping, pressing the same key will produce:
"keydown": "U+0409" (Cyrillic Capital Letter LJE)"textInput": "љ""keyup": "U+0409"
Note: The order between the text event and keyboard events may differ depending on the keyboard devices.
A.1.1 Modifier keys
Keyboard input uses modifier keys to change the normal behavior of a key. Keys associated with modifiers generate, like other keys, keydown and keyup events as shown in the example below. Some modifiers are activated while the key is being pressed down or maintained pressed such as "Alt", "Control", "Shift", "AltGraph", or "Meta". Others modifiers are activated depending on their state such as "CapsLock", "NumLock", or "Scroll". Change in the state happens when the modifier key is being pressed down. The
KeyboardEvent
interface provides convenient attributes for some common modifiers keys:
KeyboardEvent.ctrlKey
,
KeyboardEvent.shiftKey
,
KeyboardEvent.altKey
,
KeyboardEvent.metaKey
. Some operating systems simulate the "AltGraph" modifier key with the combination of the "Alt and "Control" modifier keys. Implementations are encouraged to use the "AltGraph" modifier key.
The following example describes a possible sequence of keys to generate the Unicode character Q (Latin Capital Letter Q) on a PC/AT US keyboard using a US mapping:
"keydown": "Shift", shiftKey"keydown": "U+0051" (Latin Capital Letter Q key), shiftKey"textInput": "Q""keyup": "U+0051", shiftKey"keyup": "Shift"
The following example describes a possible sequence of keys that does not generate a Unicode character (using the same configuration):
"keydown": "Control", ctrlKey"keydown": "U+0056" (Latin Capital Letter V key), ctrlKey"keyup": "U+0056", ctrlKey"keyup": "Control"
A.1.2 Dead keys
Keyboard input uses dead keys for the input of composed character sequences. Unlike the handwriting sequence, in which users enter the base character first, keyboard input requires to enter a special state when a dead key is pressed and emit the character(s) only when one of a limited number of "legal" base character is entered.
The dead keys are represented in the key identifiers set using combining diacritical marks. The sequence of keystrokes "U+0302" (Combining Circumflex Accent key) and "U+0045" (Latin Capital Letter E key) will likely produce (on a PC/AT french keyboard using a french mapping and without any modifier activated) the Unicode character ê (Latin Small Letter E With Circumflex), as preferred by the Unicode Normalization Form NFC:
"keydown": "U+0302" (Combining Circumflex Accent key)"keyup": "U+0302""keydown": "U+0045" (Latin Capital Letter E key)"textInput": "é""keyup": "U+0045"
A.1.3 Input Method Editors
Also known as front end processor, an input method editor (IME) is an application that performs the conversion between keystrokes and ideographs or other characters, usually by user-guided dictionary lookup.
This specification does not provide a representation of the input method editor (IME) events, i.e. the IME's functions and the IME context are not represented in this set. As an example, receiving a keydown for the "Accept" key identifier does not necessarily imply that the text currently selected in the IME is being accepted. It only indicates that a keystroke happened, disconnected from the IME Accept functionality. Depending on the device in use, the IME Accept functionality can be obtain using the Accept key or the Return key. Keyboard events cannot be used to determine the current state of the input method editor.
Keyboard events correspond to the events generated by the input device after the keyboard layout mapping but before the processing of the input method editor.
The following example describes a possible sequence of keys to generate the Unicode character 市 (Kanji character, part of CJK Unified Ideographs) using Japanese input methods. This example assumes that the input method editor is activated and in the Japanese-Romaji input mode. The keys "Convert" and "Accept" may be replaced by others depending on the input device in use and the configuration of the IME, e.g. it could be respectively "U+0020" (Space key) and "Enter".
"keydown": "U+0053" (Latin Capital Letter S key)"keyup": "U+0053" (Latin Capital Letter S key)"keydown": "U+0049" (Latin Capital Letter I key)"keyup": "U+0049" (Latin Capital Letter I key)"keydown": "Convert""keyup": "Convert""keydown": "Accept""textInput": "市""keyup": "Accept"
A.1.4 Default actions and cancelable keyboard events
Canceling the default action of a keydown event does not affect its respective keyup event; it will however prevent the respective textInput event from being generated. The following example describes a possible sequence of keys to generate the Unicode character Q (Latin Capital Letter Q) on a PC/AT US keyboard using a US mapping:
"keydown": "U+0051" (Latin Capital Letter Q key), shiftKey
the default action of the keydown event is prevented, e.g. by invoking
Event.preventDefault()
during the dispatch of the keydown event object.- No
"textInput" is generated.
"keyup": "U+0051", shiftKey
If the key is a modifier key, the keystroke is taken into account for the modifiers states. The following example describes a possible sequence of keys to generate the Unicode character Q (Latin Capital Letter Q) on a PC/AT US keyboard using a US mapping:
"keydown": "Shift", shiftKey
the default action of the keydown event is prevented."keydown": "U+0051" (Latin Capital Letter Q key), shiftKey"textInput": "Q""keyup": "U+0051", shiftKey"keyup": "Shift"
If the key is part of a sequence of several keystrokes, whether it is a dead key or it is contributing to an Input Method Editor sequence, the keystroke is ignored (not taken into account) only if the default action is canceled on the keydown event. Canceling a dead key on a keyup event has not effect on textInput events. The following example uses the keystrokes "U+0302" (Combining Circumflex Accent key) and "U+0045" (Latin Capital Letter E key) (on a PC/AT french keyboard using a french mapping and without any modifier activated):
"keydown": "U+0302" (Combining Circumflex Accent key)
the default action of the keydown event is prevented"keyup": "U+0302""keydown": "U+0045" (Latin Capital Letter E key)"textInput": "a""keyup": "U+0045"
A.1.5 Guidelines for defining key identifiers
Note: This section is non-normative.
The list of key identifiers contained in this appendix is not exhaustive and input devices may have to define their own key identifiers. Here is a algorithm to determine which key identifier to use:
- Determine a representation for the key by looking at the keyboard layout mapping in use (and not the keyboard device in use). This representation should be unique, as human friendly as possible, platform independent, and consistent. For example, on PC/AT US keyboards with a US mapping, the 'Q' key is mapped to the key identifier "U+0051" (Latin Capital Letter Q key), the '1/!' key is mapped to the key identifier "U+0031" (Digit One key), the key '`/~' is mapped to the key identifier "U+0060" (Grave Accent key), and the 'Enter' key is mapped to the key identifier "Enter".
- Find an appropriate mapping in the Unicode character set. There might not always be an appropriate and obvious mapping: the Unicode set contains characters and symbols, the key might generate different characters depending on the operating system, ... In general, unless the representation of the key can be mapped to a unique Unicode character, it is better to create a new one.
- If no appropriate mapping was found, create a key identifier as human friendly as possible. The key identifier must not contain white spaces. As an example, the Enter key is mapped to the key identifier "Enter" and not to "U+000A" (Line Feed), given that this key generates the character "U+000A" on Unix operating systems and the characters "U+000D" and "U+000A" on Windows operating systems.
A.2 Key identifiers set
Note: The keycodes Multiply, Add, Substract, Decimal, Separator, Divide, NumPad0, NumPad1, NumPad2, NumPad3, NumPad4, NumPad5, NumPad6, NumPad7, NumPad8, and NumPad9 are not part of this set. Use
KeyboardEvent.keyLocation
to know if a key originated from the numeric keypad.
-
"Accept"
- The Accept (Commit) key.
-
"Again"
- The Again key.
-
"AllCandidates"
- The All Candidates key.
-
"Alphanumeric"
- The Alphanumeric key.
-
"Alt"
- The Alt (Menu) key.
-
"AltGraph"
- The Alt-Graph key.
-
"Apps"
- The Application key.
-
"Attn"
- The ATTN key.
-
"BrowserBack"
- The Browser Back key.
-
"BrowserFavorites"
- The Browser Favorites key.
-
"BrowserForward"
- The Browser Forward key.
-
"BrowserHome"
- The Browser Home key.
-
"BrowserRefresh"
- The Browser Refresh key.
-
"BrowserSearch"
- The Browser Search key.
-
"BrowserStop"
- The Browser Stop key.
-
"CapsLock"
- The Caps Lock (Capital) key.
-
"Clear"
- The Clear key.
-
"CodeInput"
- The Code Input key.
-
"Compose"
- The Compose key.
-
"Control"
- The Control (Ctrl) key.
-
"Crsel"
- The Crsel key.
-
"Convert"
- The Convert key.
-
"Copy"
- The Copy key.
-
"Cut"
- The Cut key.
-
"Down"
- The Down Arrow key.
-
"End"
- The End key.
-
"Enter"
- The Enter key.
Note: This key identifier is also used for the Return (Macintosh numpad) key.
-
"EraseEof"
- The Erase EOF key.
-
"Execute"
- The Execute key.
-
"Exsel"
- The Exsel key.
-
"F1"
- The F1 key.
-
"F2"
- The F2 key.
-
"F3"
- The F3 key.
-
"F4"
- The F4 key.
-
"F5"
- The F5 key.
-
"F6"
- The F6 key.
-
"F7"
- The F7 key.
-
"F8"
- The F8 key.
-
"F9"
- The F9 key.
-
"F10"
- The F10 key.
-
"F11"
- The F11 key.
-
"F12"
- The F12 key.
-
"F13"
- The F13 key.
-
"F14"
- The F14 key.
-
"F15"
- The F15 key.
-
"F16"
- The F16 key.
-
"F17"
- The F17 key.
-
"F18"
- The F18 key.
-
"F19"
- The F19 key.
-
"F20"
- The F20 key.
-
"F21"
- The F21 key.
-
"F22"
- The F22 key.
-
"F23"
- The F23 key.
-
"F24"
- The F24 key.
-
"FinalMode"
- The Final Mode (Final) key used on some asian keyboards.
-
"Find"
- The Find key.
-
"FullWidth"
- The Full-Width Characters key.
-
"HalfWidth"
- The Half-Width Characters key.
-
"HangulMode"
- The Hangul (Korean characters) Mode key.
-
"HanjaMode"
- The Hanja (Korean characters) Mode key.
-
"Help"
- The Help key.
-
"Hiragana"
- The Hiragana (Japanese Kana characters) key.
-
"Home"
- The Home key.
-
"Insert"
- The Insert (Ins) key.
-
"JapaneseHiragana"
- The Japanese-Hiragana key.
-
"JapaneseKatakana"
- The Japanese-Katakana key.
-
"JapaneseRomaji"
- The Japanese-Romaji key.
-
"JunjaMode"
- The Junja Mode key.
-
"KanaMode"
- The Kana Mode (Kana Lock) key.
-
"KanjiMode"
- The Kanji (Japanese name for ideographic characters of Chinese origin) Mode key.
-
"Katakana"
- The Katakana (Japanese Kana characters) key.
-
"LaunchApplication1"
- The Start Application One key.
-
"LaunchApplication2"
- The Start Application Two key.
-
"LaunchMail"
- The Start Mail key.
-
"Left"
- The Left Arrow key.
-
"Meta"
- The Meta key.
-
"MediaNextTrack"
- The Media Next Track key.
-
"MediaPlayPause"
- The Media Play Pause key.
-
"MediaPreviousTrack"
- The Media Previous Track key.
-
"MediaStop"
- The Media Stok key.
-
"ModeChange"
- The Mode Change key.
-
"Nonconvert"
- The Nonconvert (Don't Convert) key.
-
"NumLock"
- The Num Lock key.
-
"PageDown"
- The Page Down (Next) key.
-
"PageUp"
- The Page Up key.
-
"Paste"
- The Paste key.
-
"Pause"
- The Pause key.
-
"Play"
- The Play key.
-
"PreviousCandidate"
- The Previous Candidate function key.
-
"PrintScreen"
- The Print Screen (PrintScrn, SnapShot) key.
-
"Process"
- The Process key.
-
"Props"
- The Props key.
-
"Right"
- The Right Arrow key.
-
"RomanCharacters"
- The Roman Characters function key.
-
"Scroll"
- The Scroll Lock key.
-
"Select"
- The Select key.
-
"SelectMedia"
- The Select Media key.
-
"Shift"
- The Shift key.
-
"Stop"
- The Stop key.
-
"Up"
- The Up Arrow key.
-
"Undo"
- The Undo key.
-
"VolumeDown"
- The Volume Down key.
-
"VolumeMute"
- The Volume Mute key.
-
"VolumeUp"
- The Volume Up key.
-
"Win"
- The Windows Logo key.
-
"Zoom"
- The Zoom key.
-
"U+0008"
- The Backspace (Back) key.
-
"U+0009"
- The Horizontal Tabulation (Tab) key.
-
"U+0018"
- The Cancel key.
-
"U+001B"
- The Escape (Esc) key.
-
"U+0020"
- The Space (Spacebar) key.
-
"U+0021"
- The Exclamation Mark (Factorial, Bang) key (!).
-
"U+0022"
- The Quotation Mark (Quote Double) key (").
-
"U+0023"
- The Number Sign (Pound Sign, Hash, Crosshatch, Octothorpe) key (#).
-
"U+0024"
- The Dollar Sign (milreis, escudo) key ($).
-
"U+0026"
- The Ampersand key (&).
-
"U+0027"
- The Apostrophe (Apostrophe-Quote, APL Quote) key (').
-
"U+0028"
- The Left Parenthesis (Opening Parenthesis) key (().
-
"U+0029"
- The Right Parenthesis (Closing Parenthesis) key ()).
-
"U+002A"
- The Asterix (Star) key (*).
-
"U+002B"
- The Plus Sign (Plus) key (+).
-
"U+002C"
- The Comma (decimal separator) sign key (,).
-
"U+002D"
- The Hyphen-minus (hyphen or minus sign) key (-).
-
"U+002E"
- The Full Stop (period, dot, decimal point) key (.).
-
"U+002F"
- The Solidus (slash, virgule, shilling) key (/).
-
"U+0030"
- The Digit Zero key (0).
-
"U+0031"
- The Digit One key (1).
-
"U+0032"
- The Digit Two key (2).
-
"U+0033"
- The Digit Three key (3).
-
"U+0034"
- The Digit Four key (4).
-
"U+0035"
- The Digit Five key (5).
-
"U+0036"
- The Digit Six key (6).
-
"U+0037"
- The Digit Seven key (7).
-
"U+0038"
- The Digit Eight key (8).
-
"U+0039"
- The Digit Nine key (9).
-
"U+003A"
- The Colon key (:).
-
"U+003B"
- The Semicolon key (;).
-
"U+003C"
- The Less-Than Sign key (<).
-
"U+003D"
- The Equals Sign key (=).
-
"U+003E"
- The Greater-Than Sign key (>).
-
"U+003F"
- The Question Mark key (?).
-
"U+0040"
- The Commercial At (@) key.
-
"U+0041"
- The Latin Capital Letter A key (A).
-
"U+0042"
- The Latin Capital Letter B key (B).
-
"U+0043"
- The Latin Capital Letter C key (C).
-
"U+0044"
- The Latin Capital Letter D key (D).
-
"U+0045"
- The Latin Capital Letter E key (E).
-
"U+0046"
- The Latin Capital Letter F key (F).
-
"U+0047"
- The Latin Capital Letter G key (G).
-
"U+0048"
- The Latin Capital Letter H key (H).
-
"U+0049"
- The Latin Capital Letter I key (I).
-
"U+004A"
- The Latin Capital Letter J key (J).
-
"U+004B"
- The Latin Capital Letter K key (K).
-
"U+004C"
- The Latin Capital Letter L key (L).
-
"U+004D"
- The Latin Capital Letter M key (M).
-
"U+004E"
- The Latin Capital Letter N key (N).
-
"U+004F"
- The Latin Capital Letter O key (O).
-
"U+0050"
- The Latin Capital Letter P key (P).
-
"U+0051"
- The Latin Capital Letter Q key (Q).
-
"U+0052"
- The Latin Capital Letter R key (R).
-
"U+0053"
- The Latin Capital Letter S key (S).
-
"U+0054"
- The Latin Capital Letter T key (T).
-
"U+0055"
- The Latin Capital Letter U key (U).
-
"U+0056"
- The Latin Capital Letter V key (V).
-
"U+0057"
- The Latin Capital Letter W key (W).
-
"U+0058"
- The Latin Capital Letter X key (X).
-
"U+0059"
- The Latin Capital Letter Y key (Y).
-
"U+005A"
- The Latin Capital Letter Z key (Z).
-
"U+005B"
- The Left Square Bracket (Opening Square Bracket) key ([).
-
"U+005C"
- The Reverse Solidus (Backslash) key (\).
-
"U+005D"
- The Right Square Bracket (Closing Square Bracket) key (]).
-
"U+005E"
- The Circumflex Accent key (^).
-
"U+005F"
- The Low Sign (Spacing Underscore, Underscore) key (_).
-
"U+0060"
- The Grave Accent (Back Quote) key (`).
-
"U+007B"
- The Left Curly Bracket (Opening Curly Bracket, Opening Brace, Brace Left) key ({).
-
"U+007C"
- The Vertical Line (Vertical Bar, Pipe) key (|).
-
"U+007D"
- The Right Curly Bracket (Closing Curly Bracket, Closing Brace, Brace Right) key (}).
-
"U+007F"
- The Delete (Del) Key.
-
"U+00A1"
- The Inverted Exclamation Mark key (¡).
-
"U+0300"
- The Combining Grave Accent (Greek Varia, Dead Grave) key.
-
"U+0301"
- The Combining Acute Accent (Stress Mark, Greek Oxia, Tonos, Dead Eacute) key.
-
"U+0302"
- The Combining Circumflex Accent (Hat, Dead Circumflex) key.
-
"U+0303"
- The Combining Tilde (Dead Tilde) key.
-
"U+0304"
- The Combining Macron (Long, Dead Macron) key.
-
"U+0306"
- The Combining Breve (Short, Dead Breve) key.
-
"U+0307"
- The Combining Dot Above (Derivative, Dead Above Dot) key.
-
"U+0308"
- The Combining Diaeresis (Double Dot Abode, Umlaut, Greek Dialytika, Double Derivative, Dead Diaeresis) key.
-
"U+030A"
- The Combining Ring Above (Dead Above Ring) key.
-
"U+030B"
- The Combining Double Acute Accent (Dead Doubleacute) key.
-
"U+030C"
- The Combining Caron (Hacek, V Above, Dead Caron) key.
-
"U+0327"
- The Combining Cedilla (Dead Cedilla) key.
-
"U+0328"
- The Combining Ogonek (Nasal Hook, Dead Ogonek) key.
-
"U+0345"
- The Combining Greek Ypogegrammeni (Greek Non-Spacing Iota Below, Iota Subscript, Dead Iota) key.
-
"U+20AC"
- The Euro Currency Sign key (€).
-
"U+3099"
- The Combining Katakana-Hiragana Voiced Sound Mark (Dead Voiced Sound) key.
-
"U+309A"
- The Combining Katakana-Hiragana Semi-Voiced Sound Mark (Dead Semivoiced Sound) key.
Appendix C: Security Considerations
- Editor:
-
Björn Höhrmann
This appendix discusses security considerations for DOM Level 3 Events implementations. The discussion is limited to security issues that arise directly from implementation of the event model, APIs and events defined in this specification. Implementations typically support other features like scripting languages, other APIs and additional events not defined in this document; these features constitute an unknown factor and are out of scope of this document. Implementers should consult the specifications of such features for their respective security considerations.
Many of the event types defined in this specification are dispatched in response to user actions. This allows malicious event listeners to gain access to information users would typically consider confidential, e.g., typos they might have made when filling out a form, if they reconsider their answer to a multiple choice question shortly before submitting a form, their typing rate or primary input mechanism. In the worst case, malicious event listeners are able to capture all user interactions and submit them to a third party through means, while not defined in DOM Level 3 Events, generally available in DOM implementations.
In DOM implementations that support facilities to load external data, events like the error event can provide access to sensitive information about the environment of the computer system or network; an example would be a malicious HTML document that attempts to embed a resource on the local network or the localhost on different ports; an embedded DOM application could then listen for error and load events to determine which other computers in a network are accessible from the local system or which ports are open on the system to prepare further attacks.
An implementation of DOM Level 3 Events alone is generally insufficient to perform attacks of this kind and the security considerations of the facilities that possibly support such attacks apply. For conformance with this specification, DOM implementations may take reasonable steps to ensure that DOM applications do not get access to confidential or sensitive information, for example, they may choose to dispatch no load events to nodes that attempt to embed resources on the local network.
The
DocumentEvent.canDispatch()
method allows DOM applications to retrieve information about which event types the implementation supports, including event types not defined in this specification. Which event types a DOM Level 3 Events implementation supports can depend on configuration settings or on additional software modules available to the implementation.
Appendix D: IDL Definitions
This appendix contains the complete OMG IDL [
OMG IDL
] for the Level 3 Document Object Model Events definitions.
The IDL files are also available as: http://www.w3.org/TR/2007/WD-DOM-Level-3-Events-20071207/idl.zip
// File: events.idl
#ifndef _EVENTS_IDL_
#define _EVENTS_IDL_
#include "dom.idl"
#include "views.idl"
#pragma prefix "dom.w3c.org"
module events
{
typedef dom::DOMString DOMString;
typedef dom::DOMTimeStamp DOMTimeStamp;
typedef dom::DOMObject DOMObject;
typedef dom::Node Node;
interface EventTarget;
interface EventListener;
// Introduced in DOM Level 2:
exception EventException {
unsigned short code;
};
// EventExceptionCode
const unsigned short UNSPECIFIED_EVENT_TYPE_ERR = 0;
// Introduced in DOM Level 3:
const unsigned short DISPATCH_REQUEST_ERR = 1;
// Introduced in DOM Level 2:
interface Event {
// PhaseType
const unsigned short CAPTURING_PHASE = 1;
const unsigned short AT_TARGET = 2;
const unsigned short BUBBLING_PHASE = 3;
readonly attribute DOMString type;
readonly attribute EventTarget target;
readonly attribute EventTarget currentTarget;
readonly attribute unsigned short eventPhase;
readonly attribute boolean bubbles;
readonly attribute boolean cancelable;
readonly attribute DOMTimeStamp timeStamp;
void stopPropagation();
void preventDefault();
void initEvent(in DOMString eventTypeArg,
in boolean canBubbleArg,
in boolean cancelableArg);
// Introduced in DOM Level 3:
readonly attribute DOMString namespaceURI;
// Introduced in DOM Level 3:
void stopImmediatePropagation();
// Introduced in DOM Level 3:
readonly attribute boolean defaultPrevented;
// Introduced in DOM Level 3:
void initEventNS(in DOMString namespaceURIArg,
in DOMString eventTypeArg,
in boolean canBubbleArg,
in boolean cancelableArg);
};
// Introduced in DOM Level 3:
interface CustomEvent : Event {
readonly attribute DOMObject detail;
void initCustomEventNS(in DOMString namespaceURIArg,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in DOMObject detailArg);
};
// Introduced in DOM Level 2:
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,
dom::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 2:
interface EventListener {
void handleEvent(in Event evt);
};
// Introduced in DOM Level 2:
interface DocumentEvent {
Event createEvent(in DOMString eventType)
raises(dom::DOMException);
// Introduced in DOM Level 3:
boolean canDispatch(in DOMString namespaceURI,
in DOMString type);
};
// Introduced in DOM Level 2:
interface UIEvent : Event {
readonly attribute views::AbstractView view;
readonly attribute long detail;
void initUIEvent(in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in long detailArg);
// Introduced in DOM Level 3:
void initUIEventNS(in DOMString namespaceURIArg,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in long detailArg);
};
// Introduced in DOM Level 3:
interface TextEvent : UIEvent {
readonly attribute DOMString data;
void initTextEvent(in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in DOMString dataArg);
void initTextEventNS(in DOMString namespaceURIArg,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in DOMString dataArg);
};
// Introduced in DOM Level 3:
interface KeyboardEvent : UIEvent {
// KeyLocationCode
const unsigned long DOM_KEY_LOCATION_STANDARD = 0x00;
const unsigned long DOM_KEY_LOCATION_LEFT = 0x01;
const unsigned long DOM_KEY_LOCATION_RIGHT = 0x02;
const unsigned long DOM_KEY_LOCATION_NUMPAD = 0x03;
readonly attribute DOMString keyIdentifier;
readonly attribute unsigned long keyLocation;
readonly attribute boolean ctrlKey;
readonly attribute boolean shiftKey;
readonly attribute boolean altKey;
readonly attribute boolean metaKey;
boolean getModifierState(in DOMString keyIdentifierArg);
void initKeyboardEvent(in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in DOMString keyIdentifierArg,
in unsigned long keyLocationArg,
in DOMString modifiersListArg);
void initKeyboardEventNS(in DOMString namespaceURIArg,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in DOMString keyIdentifierArg,
in unsigned long keyLocationArg,
in DOMString modifiersListArg);
};
// Introduced in DOM Level 2:
interface MouseEvent : UIEvent {
readonly attribute long screenX;
readonly attribute long screenY;
readonly attribute long clientX;
readonly attribute long clientY;
readonly attribute boolean ctrlKey;
readonly attribute boolean shiftKey;
readonly attribute boolean altKey;
readonly attribute boolean metaKey;
readonly attribute unsigned short button;
readonly attribute EventTarget relatedTarget;
void initMouseEvent(in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in long detailArg,
in long screenXArg,
in long screenYArg,
in long clientXArg,
in long clientYArg,
in boolean ctrlKeyArg,
in boolean altKeyArg,
in boolean shiftKeyArg,
in boolean metaKeyArg,
in unsigned short buttonArg,
in EventTarget relatedTargetArg);
// Introduced in DOM Level 3:
boolean getModifierState(in DOMString keyIdentifierArg);
// Introduced in DOM Level 3:
void initMouseEventNS(in DOMString namespaceURIArg,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in long detailArg,
in long screenXArg,
in long screenYArg,
in long clientXArg,
in long clientYArg,
in unsigned short buttonArg,
in EventTarget relatedTargetArg,
in DOMString modifiersListArg);
};
// Introduced in DOM Level 3:
interface WheelEvent : MouseEvent {
readonly attribute long deltaX;
readonly attribute long deltaY;
readonly attribute long deltaZ;
void initWheelEventNS(in DOMString namespaceURIArg,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in long detailArg,
in long screenXArg,
in long screenYArg,
in long clientXArg,
in long clientYArg,
in unsigned short buttonArg,
in EventTarget relatedTargetArg,
in DOMString modifiersListArg,
in long deltaXArg,
in long deltaYArg,
in long deltaZArg);
};
// Introduced in DOM Level 3:
interface MouseWheelEvent : MouseEvent {
readonly attribute long wheelDelta;
void initMouseWheelEventNS(in DOMString namespaceURIArg,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in long detailArg,
in long screenXArg,
in long screenYArg,
in long clientXArg,
in long clientYArg,
in unsigned short buttonArg,
in EventTarget relatedTargetArg,
in DOMString modifiersListArg,
in long wheelDeltaArg);
};
// Introduced in DOM Level 2:
interface MutationEvent : Event {
// attrChangeType
const unsigned short MODIFICATION = 1;
const unsigned short ADDITION = 2;
const unsigned short REMOVAL = 3;
readonly attribute Node relatedNode;
readonly attribute DOMString prevValue;
readonly attribute DOMString newValue;
readonly attribute DOMString attrName;
readonly attribute unsigned short attrChange;
void initMutationEvent(in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in Node relatedNodeArg,
in DOMString prevValueArg,
in DOMString newValueArg,
in DOMString attrNameArg,
in unsigned short attrChangeArg);
// Introduced in DOM Level 3:
void initMutationEventNS(in DOMString namespaceURIArg,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in Node relatedNodeArg,
in DOMString prevValueArg,
in DOMString newValueArg,
in DOMString attrNameArg,
in unsigned short attrChangeArg);
};
// Introduced in DOM Level 3:
interface MutationNameEvent : MutationEvent {
readonly attribute DOMString prevNamespaceURI;
readonly attribute DOMString prevNodeName;
// Introduced in DOM Level 3:
void initMutationNameEvent(in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in Node relatedNodeArg,
in DOMString prevNamespaceURIArg,
in DOMString prevNodeNameArg);
// Introduced in DOM Level 3:
void initMutationNameEventNS(in DOMString namespaceURIArg,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in Node relatedNodeArg,
in DOMString prevNamespaceURIArg,
in DOMString prevNodeNameArg);
};
};
#endif // _EVENTS_IDL_
Appendix E: Java Language Binding
This appendix contains the complete Java [
Java
] bindings for the Level 3 Document Object Model Events.
The Java files are also available as http://www.w3.org/TR/2007/WD-DOM-Level-3-Events-20071207/java-binding.zip
org\w3c\dom\events\EventException.java:
package org.w3c.dom.events;
public class EventException extends RuntimeException {
public EventException(short code, String message) {
super(message);
this.code = code;
}
public short code;
// EventExceptionCode
public static final short UNSPECIFIED_EVENT_TYPE_ERR = 0;
public static final short DISPATCH_REQUEST_ERR = 1;
}
org\w3c\dom\events\Event.java:
package org.w3c.dom.events;
public interface Event {
// PhaseType
public static final short CAPTURING_PHASE = 1;
public static final short AT_TARGET = 2;
public static final short BUBBLING_PHASE = 3;
public String getType();
public EventTarget getTarget();
public EventTarget getCurrentTarget();
public short getEventPhase();
public boolean getBubbles();
public boolean getCancelable();
public long getTimeStamp();
public void stopPropagation();
public void preventDefault();
public void initEvent(String eventTypeArg,
boolean canBubbleArg,
boolean cancelableArg);
public String getNamespaceURI();
public void stopImmediatePropagation();
public boolean getDefaultPrevented();
public void initEventNS(String namespaceURIArg,
String eventTypeArg,
boolean canBubbleArg,
boolean cancelableArg);
}
org\w3c\dom\events\CustomEvent.java:
package org.w3c.dom.events;
public interface CustomEvent extends Event {
public Object getDetail();
public void initCustomEventNS(String namespaceURIArg,
String typeArg,
boolean canBubbleArg,
boolean cancelableArg,
Object detailArg);
}
org\w3c\dom\events\EventTarget.java:
package org.w3c.dom.events;
import org.w3c.dom.DOMException;
public interface EventTarget {
public void addEventListener(String type,
EventListener listener,
boolean useCapture);
public void removeEventListener(String type,
EventListener listener,
boolean useCapture);
public boolean dispatchEvent(Event evt)
throws EventException, DOMException;
public void addEventListenerNS(String namespaceURI,
String type,
EventListener listener,
boolean useCapture);
public void removeEventListenerNS(String namespaceURI,
String type,
EventListener listener,
boolean useCapture);
}
org\w3c\dom\events\EventListener.java:
package org.w3c.dom.events;
public interface EventListener {
public void handleEvent(Event evt);
}
org\w3c\dom\events\DocumentEvent.java:
package org.w3c.dom.events;
import org.w3c.dom.DOMException;
public interface DocumentEvent {
public Event createEvent(String eventType)
throws DOMException;
public boolean canDispatch(String namespaceURI,
String type);
}
org\w3c\dom\events\UIEvent.java:
package org.w3c.dom.events;
import org.w3c.dom.views.AbstractView;
public interface UIEvent extends Event {
public AbstractView getView();
public int getDetail();
public void initUIEvent(String typeArg,
boolean canBubbleArg,
boolean cancelableArg,
AbstractView viewArg,
int detailArg);
public void initUIEventNS(String namespaceURIArg,
String typeArg,
boolean canBubbleArg,
boolean cancelableArg,
AbstractView viewArg,
int detailArg);
}
org\w3c\dom\events\TextEvent.java:
package org.w3c.dom.events;
import org.w3c.dom.views.AbstractView;
public interface TextEvent extends UIEvent {
public String getData();
public void initTextEvent(String typeArg,
boolean canBubbleArg,
boolean cancelableArg,
AbstractView viewArg,
String dataArg);
public void initTextEventNS(String namespaceURIArg,
String typeArg,
boolean canBubbleArg,
boolean cancelableArg,
AbstractView viewArg,
String dataArg);
}
org\w3c\dom\events\KeyboardEvent.java:
package org.w3c.dom.events;
import org.w3c.dom.views.AbstractView;
public interface KeyboardEvent extends UIEvent {
// KeyLocationCode
public static final int DOM_KEY_LOCATION_STANDARD = 0x00;
public static final int DOM_KEY_LOCATION_LEFT = 0x01;
public static final int DOM_KEY_LOCATION_RIGHT = 0x02;
public static final int DOM_KEY_LOCATION_NUMPAD = 0x03;
public String getKeyIdentifier();
public int getKeyLocation();
public boolean getCtrlKey();
public boolean getShiftKey();
public boolean getAltKey();
public boolean getMetaKey();
public boolean getModifierState(String keyIdentifierArg);
public void initKeyboardEvent(String typeArg,
boolean canBubbleArg,
boolean cancelableArg,
AbstractView viewArg,
String keyIdentifierArg,
int keyLocationArg,
String modifiersListArg);
public void initKeyboardEventNS(String namespaceURIArg,
String typeArg,
boolean canBubbleArg,
boolean cancelableArg,
AbstractView viewArg,
String keyIdentifierArg,
int keyLocationArg,
String modifiersListArg);
}
org\w3c\dom\events\MouseEvent.java:
package org.w3c.dom.events;
import org.w3c.dom.views.AbstractView;
public interface MouseEvent extends UIEvent {
public int getScreenX();
public int getScreenY();
public int getClientX();
public int getClientY();
public boolean getCtrlKey();
public boolean getShiftKey();
public boolean getAltKey();
public boolean getMetaKey();
public short getButton();
public EventTarget getRelatedTarget();
public void initMouseEvent(String typeArg,
boolean canBubbleArg,
boolean cancelableArg,
AbstractView viewArg,
int detailArg,
int screenXArg,
int screenYArg,
int clientXArg,
int clientYArg,
boolean ctrlKeyArg,
boolean altKeyArg,
boolean shiftKeyArg,
boolean metaKeyArg,
short buttonArg,
EventTarget relatedTargetArg);
public boolean getModifierState(String keyIdentifierArg);
public void initMouseEventNS(String namespaceURIArg,
String typeArg,
boolean canBubbleArg,
boolean cancelableArg,
AbstractView viewArg,
int detailArg,
int screenXArg,
int screenYArg,
int clientXArg,
int clientYArg,
short buttonArg,
EventTarget relatedTargetArg,
String modifiersListArg);
}
org\w3c\dom\events\WheelEvent.java:
package org.w3c.dom.events;
import org.w3c.dom.views.AbstractView;
public interface WheelEvent extends MouseEvent {
public int getWheelDeltaX();
public int getWheelDeltaY();
public int getWheelDeltaZ();
public void initWheelEventNS(String namespaceURIArg,
String typeArg,
boolean canBubbleArg,
boolean cancelableArg,
AbstractView viewArg,
int detailArg,
int screenXArg,
int screenYArg,
int clientXArg,
int clientYArg,
short buttonArg,
EventTarget relatedTargetArg,
String modifiersListArg,
int deltaXArg,
int deltaYArg,
int deltaZArg);
}
org\w3c\dom\events\MouseWheelEvent.java:
package org.w3c.dom.events;
import org.w3c.dom.views.AbstractView;
public interface MouseWheelEvent extends MouseEvent {
public int getWheelDelta();
public void initMouseWheelEventNS(String namespaceURIArg,
String typeArg,
boolean canBubbleArg,
boolean cancelableArg,
AbstractView viewArg,
int detailArg,
int screenXArg,
int screenYArg,
int clientXArg,
int clientYArg,
short buttonArg,
EventTarget relatedTargetArg,
String modifiersListArg,
int wheelDeltaArg);
}
org\w3c\dom\events\MutationEvent.java:
package org.w3c.dom.events;
import org.w3c.dom.Node;
public interface MutationEvent extends Event {
// attrChangeType
public static final short MODIFICATION = 1;
public static final short ADDITION = 2;
public static final short REMOVAL = 3;
public Node getRelatedNode();
public String getPrevValue();
public String getNewValue();
public String getAttrName();
public short getAttrChange();
public void initMutationEvent(String typeArg,
boolean canBubbleArg,
boolean cancelableArg,
Node relatedNodeArg,
String prevValueArg,
String newValueArg,
String attrNameArg,
short attrChangeArg);
public void initMutationEventNS(String namespaceURIArg,
String typeArg,
boolean canBubbleArg,
boolean cancelableArg,
Node relatedNodeArg,
String prevValueArg,
String newValueArg,
String attrNameArg,
short attrChangeArg);
}
org\w3c\dom\events\MutationNameEvent.java:
package org.w3c.dom.events;
import org.w3c.dom.Node;
public interface MutationNameEvent extends MutationEvent {
public String getPrevNamespaceURI();
public String getPrevNodeName();
public void initMutationNameEvent(String typeArg,
boolean canBubbleArg,
boolean cancelableArg,
Node relatedNodeArg,
String prevNamespaceURIArg,
String prevNodeNameArg);
public void initMutationNameEventNS(String namespaceURIArg,
String typeArg,
boolean canBubbleArg,
boolean cancelableArg,
Node relatedNodeArg,
String prevNamespaceURIArg,
String prevNodeNameArg);
}
Appendix G: Acknowledgements
Many people contributed to the DOM specifications (Level 1, 2 or 3), including participants of the DOM Working Group and the DOM Interest Group. We especially thank the following:
Andrew Watson (Object Management Group), Andy Heninger (IBM), Angel Diaz (IBM), Arnaud Le Hors (W3C and IBM), Ashok Malhotra (IBM and Microsoft), Ben Chang (Oracle), Bill Smith (Sun), Bill Shea (Merrill Lynch), Bob Sutor (IBM), Chris Lovett (Microsoft), Chris Wilson (Microsoft), David Brownell (Sun), David Ezell (Hewlett-Packard Company), David Singer (IBM), Dimitris Dimitriadis (Improve AB and invited expert), Don Park (invited), Elena Litani (IBM), Eric Vasilik (Microsoft), Gavin Nicol (INSO), Ian Jacobs (W3C), James Clark (invited), James Davidson (Sun), Jared Sorensen (Novell), Jeroen van Rotterdam (X-Hive Corporation), Joe Kesselman (IBM), Joe Lapp (webMethods), Joe Marini (Macromedia), Johnny Stenback (Netscape/AOL), Jon Ferraiolo (Adobe), Jonathan Marsh (Microsoft), Jonathan Robie (Texcel Research and Software AG), Kim Adamson-Sharpe (SoftQuad Software Inc.), Lauren Wood (SoftQuad Software Inc., former Chair), Laurence Cable (Sun), Mark Davis (IBM), Mark Scardina (Oracle), Martin Dürst (W3C), Mary Brady (NIST), Mick Goulish (Software AG), Mike Champion (Arbortext and Software AG), Miles Sabin (Cromwell Media), Patti Lutsky (Arbortext), Paul Grosso (Arbortext), Peter Sharpe (SoftQuad Software Inc.), Phil Karlton (Netscape), Philippe Le Hégaret (W3C, W3C Team Contact and former Chair), Ramesh Lekshmynarayanan (Merrill Lynch), Ray Whitmer (iMall, Excite@Home, and Netscape/AOL, Chair), Rezaur Rahman (Intel), Rich Rollman (Microsoft), Rick Gessner (Netscape), Rick Jelliffe (invited), Rob Relyea (Microsoft), Scott Isaacs (Microsoft), Sharon Adler (INSO), Steve Byrne (JavaSoft), Tim Bray (invited), Tim Yu (Oracle), Tom Pixley (Netscape/AOL), Vidur Apparao (Netscape), Vinod Anupam (Lucent).
After publication of this document as Working Group Note in November 2003, the participants of the WebAPI Working Group resumed development of this document:
Anne van Kesteren (Opera Software), Arun Ranganathan (AOL), Björn Höhrmann, Charles McCathieNevile (Opera Software, Co-Chair), Christophe Jolif (ILOG), Dean Jackson (W3C, W3C Team Contact), Doug Schepers (Vectoreal), Gorm Haug Eriksen (Opera Software), Ian Davis (Talis Information Limited), Ian Hickson (Google), John Robinson (AOL), Jonas Sicking (Mozilla Foundation), Luca Mascaro (HTML Writers Guild), Maciej Stachowiak (Apple Computer), Marc Hadley (Sun Microsystems), Michael Shenfield (Research In Motion), Robin Berjon, (Expway, Co-Chair) , Scott Hayman (Research In Motion), Stéphane Sire (IntuiLab), T.V. Raman (Google),
Thanks to all those who have helped to improve this specification by sending suggestions and corrections (Please, keep bugging us with your issues!).
Many thanks to Brad Pettit, Dylan Schiemann, David Flanagan, Steven Pemberton, Curt Arnold, Al Gilman, Misha Wolf, Sigurd Lerstad, Michael B. Allen, Alexander J. Vincent, Martin Dürst, Ken Rehor, and, Cameron McCormack, for their review and comments of this document.
Special thanks to the DOM Conformance Test Suites contributors: Fred Drake, Mary Brady (NIST), Rick Rivello (NIST), Robert Clary (Netscape), Neil Delima (IBM), with a special mention to Curt Arnold.
G.1 Production Systems
This specification was written in XML. The HTML, OMG IDL, Java and ECMAScript bindings were all produced automatically.
Thanks to Joe English, author of cost, which was used as the basis for producing DOM Level 1. Thanks also to Gavin Nicol, who wrote the scripts which run on top of cost. Arnaud Le Hors and Philippe Le Hégaret maintained the scripts.
After DOM Level 1, we used Xerces as the basis DOM implementation and wish to thank the authors. Philippe Le Hégaret and Arnaud Le Hors wrote the Java programs which are the DOM application.
Thanks also to Jan Kärrman, author of html2ps, which we use in creating the PostScript version of the specification.
