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.
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.
Figure: graphical representation of an event dispatched in a DOM tree using the DOM event flow [SVG 1.0 version]
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.
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.
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.
Implementations may have a default action associated with an event type. 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.
The default actions are not part of the DOM Event flow. Before invoking a default action, the implementation must first dispatch the event as described in the Event dispatch and DOM event flow.
A cancelable event is an event associated with a default action which is allowed to be canceled during the DOM event flow. At any phase during the event flow, the triggered event listeners have the option of canceling the default action or allowing the default action to proceed. In the case of the hyperlink in the browser, canceling the action would have the result of not activating the hyperlink. Not all events defined in this specification are cancelable events. See also Default actions and cancelable keyboard events.
Different implementations will specify their own default actions, if any, associated with each event. The DOM Events specification does not attempt to specify these actions.
This specification does not provide mechanisms for accessing default actions or adding new ones.
Implementations could react to an event before dispatching it and make changes to the display and the DOM tree. Preventing the default action of such an event will reverse these changes. A good example is the attribute HTMLInputElement.checked
: as described in [DOM Level 2 HTML], the value of this attribute may be changed before the dispatch of the event; the user clicks on the radio button, the radio button is being checked (or unchecked) on the display, the attribute HTMLInputElement.checked
is changed as well, and then the device event type click is being dispatched. If the default action of the device event type is prevented, or if the default action attached to the DOMActivate event type is prevented, the attribute HTMLInputElement.checked
will need to be changed back to its original value.
(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.
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.
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, 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 |
mousemultiwheel | Yes | Yes | Document , Element |
MouseMultiWheelEvent |
mousewheel | Yes | Yes | Document , Element |
MouseWheelEvent |
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 cannot 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.
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.
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.
// 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); };
An integer indicating which phase of the event flow is being processed as defined in Event dispatch and DOM event flow.
AT_TARGET
BUBBLING_PHASE
CAPTURING_PHASE
bubbles
of type boolean
, readonlytrue
, otherwise the value is false
.cancelable
of type boolean
, readonlytrue
, otherwise the value is false
.currentTarget
of type EventTarget
, readonlyEventTarget
whose EventListeners
are currently being processed. This is particularly useful during the capture and bubbling phases. This attribute could contain the target node or a target ancestor when used with the Event dispatch and DOM event flow.defaultPrevented
of type boolean
, readonly, introduced in DOM Level 3Event.preventDefault()
has been called for this event.eventPhase
of type unsigned short
, readonlynamespaceURI
of type DOMString
, readonly, introduced in DOM Level 3null
if it is unspecified.Event.initEvent()
, set the value to null.target
of type EventTarget
, readonlytimeStamp
of type DOMTimeStamp
, readonlytimeStamp
may be not available for all events. When not available, the value is 0
.type
of type DOMString
, readonlyinitEvent
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.Event.type
attribute to eventTypeArg
, and Event.namespaceURI
to null
. To initialize an event with a namespace URI, use the Event.initEventNS()
method.
eventTypeArg
of type DOMString
Event.type
, the local name of the event type.canBubbleArg
of type boolean
Event.bubbles
. This parameter overrides the intrinsic bubbling behavior of the event.cancelableArg
of type boolean
Event.cancelable
. This parameter overrides the intrinsic cancelable behavior of the event.initEventNS
introduced in DOM Level 3Event
object. This method has the same behavior as Event.initEvent()
.
namespaceURIArg
of type DOMString
Event.namespaceURI
, the namespace URI associated with this event, or null
if no namespace.eventTypeArg
of type DOMString
Event.initEvent()
method for a description of this parameter.canBubbleArg
of type boolean
Event.initEvent()
method for a description of this parameter.cancelableArg
of type boolean
Event.initEvent()
method for a description of this parameter.preventDefault
Note: This method does not stop the event propagation; use Event.stopPropagation()
or Event.stopImmediatePropagation()
for that effect.
stopImmediatePropagation
introduced in DOM Level 3Event.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.
stopPropagation
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.
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.
// 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); };
initCustomEventNS
CustomEvent
object. This method has the same behavior as Event.initEventNS()
.
namespaceURIArg
of type DOMString
Event.initEventNS()
method for a description of this parameter.typeArg
of type DOMString
Event.initEventNS()
method for a description of this parameter.canBubbleArg
of type boolean
Event.initEventNS()
method for a description of this parameter.cancelableArg
of type boolean
Event.initEventNS()
method for a description of this parameter.detailArg
of type DOMObject
CustomEvent.detail
. This value may be null
.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.
// 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); };
addEventListener
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
.
type
of type DOMString
Event.type
associated with the event for which the user is registering.listener
of type EventListener
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
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.addEventListenerNS
introduced in DOM Level 3useCapture
parameter, on the capture phase of the DOM event flow or its target and bubbling phases.
namespaceURI
of type DOMString
Event.namespaceURI
associated with the event for which the user is registering.type
of type DOMString
EventTarget.addEventListener()
method for a description of this parameter.listener
of type EventListener
EventTarget.addEventListener()
method for a description of this parameter.useCapture
of type boolean
EventTarget.addEventListener()
method for a description of this parameter.dispatchEvent
modified in DOM Level 3EventTarget
object on which dispatchEvent
is called.
evt
of type Event
|
Indicates whether any of the listeners which handled the event called |
UNSPECIFIED_EVENT_TYPE_ERR: Raised if the DISPATCH_REQUEST_ERR: Raised if the |
|
|
NOT_SUPPORTED_ERR: Raised if the INVALID_CHARACTER_ERR: Raised if |
removeEventListener
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
.
type
of type DOMString
Event.type
for which the user registered the event listener.listener
of type EventListener
EventListener
to be removed.useCapture
of type boolean
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.removeEventListenerNS
introduced in DOM Level 3removeEventListenerNS
with arguments which do not identify any currently registered EventListener
on the EventTarget
has no effect.
namespaceURI
of type DOMString
Event.namespaceURI
associated with the event for which the user registered the event listener.type
of type DOMString
EventTarget.removeEventListener()
method for a description of this parameter.listener
of type EventListener
EventTarget.removeEventListener()
method for a description of this parameter.useCapture
of type boolean
EventTarget.removeEventListener()
method for a description of this parameter.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.
// Introduced in DOM Level 2: interface EventListener { void handleEvent(in Event evt); };
Event operations may throw an EventException
as specified in their method descriptions.
// 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;
An integer indicating the type of error generated.
DISPATCH_REQUEST_ERR
, introduced in DOM Level 3.Event
object is already dispatched in the tree.UNSPECIFIED_EVENT_TYPE_ERR
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.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.
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.
// 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); };
canDispatch
introduced in DOM Level 3namespaceURI
of type DOMString
Event.namespaceURI
of the event.type
of type DOMString
Event.type
of the event.
|
|
createEvent
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'.
The newly created event object. |
|
NOT_SUPPORTED_ERR: Raised if the implementation does not support the |
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.
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.
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.
// 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); };
initUIEvent
UIEvent
object. This method has the same behavior as Event.initEvent()
.
typeArg
of type DOMString
Event.initEvent()
method for a description of this parameter.canBubbleArg
of type boolean
Event.initEvent()
method for a description of this parameter.cancelableArg
of type boolean
Event.initEvent()
method for a description of this parameter.viewArg
of type views::AbstractView
UIEvent.view
. This value may be null
.detailArg
of type long
UIEvent.detail
.initUIEventNS
introduced in DOM Level 3UIEvent
object. This method has the same behavior as Event.initEventNS()
.
namespaceURIArg
of type DOMString
Event.initEventNS()
method for a description of this parameter.typeArg
of type DOMString
Event.initEventNS()
method for a description of this parameter.canBubbleArg
of type boolean
Event.initEventNS()
method for a description of this parameter.cancelableArg
of type boolean
Event.initEventNS()
method for a description of this parameter.viewArg
of type views::AbstractView
UIEvent.initUIEvent()
method for a description of this parameter.detailArg
of type long
UIEvent.initUIEvent()
method for a description of this parameter.The User Interface event types are listed below.
Type | DOMActivate |
---|---|
Namespace | None |
Interface | UIEvent |
Cancelable | Yes |
Bubbles | Yes |
Target | Element |
Context info | UIEvent.view is in use. |
Type | DOMFocusIn |
---|---|
Namespace | None |
Interface | UIEvent |
Cancelable | No |
Bubbles | Yes |
Target | Element |
Context info | UIEvent.view is in use. |
Type | DOMFocusOut |
---|---|
Namespace | None |
Interface | UIEvent |
Cancelable | No |
Bubbles | Yes |
Target | Element |
Context info | UIEvent.view is in use. |
Type | focus |
---|---|
Namespace | None |
Interface | UIEvent |
Cancelable | No |
Bubbles | No |
Target | Element |
Context info | UIEvent.view is in use. |
Type | blur |
---|---|
Namespace | None |
Interface | UIEvent |
Cancelable | No |
Bubbles | No |
Target | Element |
Context info | UIEvent.view is in use. |
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.
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.
// 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); };
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.initTextEvent
TextEvent
object. This method has the same behavior as UIEvent.initUIEvent()
. The value of UIEvent.detail
remains undefined.
typeArg
of type DOMString
UIEvent.initUIEvent()
method for a description of this parameter.canBubbleArg
of type boolean
UIEvent.initUIEvent()
method for a description of this parameter.cancelableArg
of type boolean
UIEvent.initUIEvent()
method for a description of this parameter.viewArg
of type views::AbstractView
UIEvent.initUIEvent()
method for a description of this parameter.dataArg
of type DOMString
TextEvent.data
.initTextEventNS
TextEvent
object. This method has the same behavior as UIEvent.initUIEventNS()
. The value of UIEvent.detail
remains undefined.
namespaceURIArg
of type DOMString
UIEvent.initUIEventNS()
method for a description of this parameter.typeArg
of type DOMString
UIEvent.initUIEventNS()
method for a description of this parameter.canBubbleArg
of type boolean
UIEvent.initUIEventNS()
method for a description of this parameter.cancelableArg
of type boolean
UIEvent.initUIEventNS()
method for a description of this parameter.viewArg
of type views::AbstractView
UIEvent.initUIEventNS()
method for a description of this parameter.dataArg
of type DOMString
TextEvent.initTextEvent()
method for a description of this parameter.The text event type is listed below.
Type | textInput |
---|---|
Namespace | None |
Interface | TextEvent |
Cancelable | Yes |
Bubbles | Yes |
Target | Element |
Context info | UIEvent.view and TextEvent.data are in use. |
(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.
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.
// 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); };
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.
DOM_KEY_LOCATION_LEFT
DOM_KEY_LOCATION_NUMPAD
DOM_KEY_LOCATION_RIGHT
DOM_KEY_LOCATION_STANDARD
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
, readonlykeyLocation
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.getModifierState
keyIdentifierArg
of type DOMString
"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
.
|
|
initKeyboardEvent
KeyboardEvent
object. This method has the same behavior as UIEvent.initUIEvent()
. The value of UIEvent.detail
remains undefined.
typeArg
of type DOMString
UIEvent.initUIEvent()
method for a description of this parameter.canBubbleArg
of type boolean
UIEvent.initUIEvent()
method for a description of this parameter.cancelableArg
of type boolean
UIEvent.initUIEvent()
method for a description of this parameter.viewArg
of type views::AbstractView
UIEvent.initUIEvent()
method for a description of this parameter.keyIdentifierArg
of type DOMString
KeyboardEvent.keyIdentifier
.keyLocationArg
of type unsigned long
KeyboardEvent.keyLocation
.modifiersListArg
of type DOMString
"Control Alt"
will mark the control and alt modifiers as activated.initKeyboardEventNS
KeyboardEvent
object. This method has the same behavior as UIEvent.initUIEventNS()
. The value of UIEvent.detail
remains undefined.
namespaceURIArg
of type DOMString
UIEvent.initUIEventNS()
method for a description of this parameter.typeArg
of type DOMString
UIEvent.initUIEventNS()
method for a description of this parameter.canBubbleArg
of type boolean
UIEvent.initUIEventNS()
method for a description of this parameter.cancelableArg
of type boolean
UIEvent.initUIEventNS()
method for a description of this parameter.viewArg
of type views::AbstractView
UIEvent.initUIEventNS()
method for a description of this parameter.keyIdentifierArg
of type DOMString
KeyboardEvent.initKeyboardEvent()
method for a description of this parameter.keyLocationArg
of type unsigned long
KeyboardEvent.initKeyboardEvent()
method for a description of this parameter.modifiersListArg
of type DOMString
KeyboardEvent.initKeyboardEvent()
method for a description of this parameter.Depending on the character generation device, keyboard events may or may not be generated.
The keyboard event types are listed below.
Type | keydown |
---|---|
Namespace | None |
Interface | KeyboardEvent |
Cancelable | Yes |
Bubbles | Yes |
Target | Element |
Context info | UIEvent.view , KeyboardEvent.keyIdentifier , KeyboardEvent.keyLocation , KeyboardEvent.altKey , KeyboardEvent.shiftKey , KeyboardEvent.ctrlKey , and KeyboardEvent.metaKey are in use. |
Type | keyup |
---|---|
Namespace | None |
Interface | KeyboardEvent |
Cancelable | Yes |
Bubbles | Yes |
Target | Element |
Context info | UIEvent.view , KeyboardEvent.keyIdentifier , and KeyboardEvent.keyLocation are in use. KeyboardEvent.altKey , KeyboardEvent.shiftKey , KeyboardEvent.ctrlKey , and KeyboardEvent.metaKey are in use unless the KeyboardEvent.keyIdentifier corresponds to the key modifier itself. |
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.
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).
// 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); };
altKey
of type boolean
, readonlyKeyboardEvent.altKey
attribute.button
of type unsigned short
, readonlybutton
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
, readonlyclientY
of type long
, readonlyctrlKey
of type boolean
, readonlyKeyboardEvent.ctrlKey
attribute.metaKey
of type boolean
, readonlyKeyboardEvent.metaKey
attribute.relatedTarget
of type EventTarget
, readonlyEventTarget
related to a UI event, depending on the type of event.screenX
of type long
, readonlyscreenY
of type long
, readonlyshiftKey
of type boolean
, readonlyKeyboardEvent.shiftKey
attribute.getModifierState
introduced in DOM Level 3keyIdentifierArg
of type DOMString
KeyboardEvent.getModifierState()
method for a description of this parameter.
|
|
initMouseEvent
MouseEvent
object. This method has the same behavior as UIEvent.initUIEvent()
.
typeArg
of type DOMString
UIEvent.initUIEvent()
method for a description of this parameter.canBubbleArg
of type boolean
UIEvent.initUIEvent()
method for a description of this parameter.cancelableArg
of type boolean
UIEvent.initUIEvent()
method for a description of this parameter.viewArg
of type views::AbstractView
UIEvent.initUIEvent()
method for a description of this parameter.detailArg
of type long
UIEvent.initUIEvent()
method for a description of this parameter.screenXArg
of type long
MouseEvent.screenX
.screenYArg
of type long
MouseEvent.screenY
.clientXArg
of type long
MouseEvent.clientX
.clientYArg
of type long
MouseEvent.clientY
.ctrlKeyArg
of type boolean
MouseEvent.ctrlKey
.altKeyArg
of type boolean
MouseEvent.altKey
.shiftKeyArg
of type boolean
MouseEvent.shiftKey
.metaKeyArg
of type boolean
MouseEvent.metaKey
.buttonArg
of type unsigned short
MouseEvent.button
.relatedTargetArg
of type EventTarget
MouseEvent.relatedTarget
. This value may be null
.initMouseEventNS
introduced in DOM Level 3MouseEvent
object. This method has the same behavior as UIEvent.initUIEventNS()
.
namespaceURIArg
of type DOMString
UIEvent.initUIEventNS()
method for a description of this parameter.typeArg
of type DOMString
UIEvent.initUIEventNS()
method for a description of this parameter.canBubbleArg
of type boolean
UIEvent.initUIEventNS()
method for a description of this parameter.cancelableArg
of type boolean
UIEvent.initUIEventNS()
method for a description of this parameter.viewArg
of type views::AbstractView
UIEvent.initUIEventNS()
method for a description of this parameter.detailArg
of type long
UIEvent.initUIEventNS()
method for a description of this parameter.screenXArg
of type long
MouseEvent.initMouseEvent()
method for a description of this parameter.screenYArg
of type long
MouseEvent.initMouseEvent()
method for a description of this parameter.clientXArg
of type long
MouseEvent.initMouseEvent()
method for a description of this parameter.clientYArg
of type long
MouseEvent.initMouseEvent()
method for a description of this parameter.buttonArg
of type unsigned short
MouseEvent.initMouseEvent()
method for a description of this parameter.relatedTargetArg
of type EventTarget
MouseEvent.initMouseEvent()
method for a description of this parameter.modifiersListArg
of type DOMString
KeyboardEvent.initKeyboardEventNS()
method for a description of this parameter.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.
Type | click |
---|---|
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. The attribute value is 1 when the user begins this action and increments by 1 for each click. |
Type | dblclick |
---|---|
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. |
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 . |
Type | mouseup |
---|---|
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. |
Type | mouseover |
---|---|
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 , and UIEvent.view are in use. MouseEvent.relatedTarget indicates the event target a pointing device is exiting, if any. |
Type | mousemove |
---|---|
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 , and UIEvent.view are in use. |
Type | mouseout |
---|---|
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 , and UIEvent.view are in use. MouseEvent.relatedTarget indicates the event target a pointing device is entering, if any. |
This module defines the feature MouseMultiWheelEvents 3.0 and depends on the feature MouseEvents 3.0.
Multi wheels are devices that can be rotated in one or more spatial dimensions. 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 delta attributes of MouseMultiWheelEvent
objects indicate the distance of the rotation. The measurement unit depends on the environment configuration. The sign of the delta value should indicate the direction of the rotation.
The MouseMultiWheelEvent
interface provides specific contextual information associated with mouse multi wheel events.
To create an instance of the MouseMultiWheelEvent
interface, use the DocumentEvent.createEvent("MouseMultiWheelEvent")
method call.
// Introduced in DOM Level 3: interface MouseMultiWheelEvent : MouseEvent { readonly attribute long wheelDeltaX; readonly attribute long wheelDeltaY; readonly attribute long wheelDeltaZ; void initMouseMultiWheelEventNS(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 wheelDeltaXArg, in long wheelDeltaYArg, in long wheelDeltaZArg); };
wheelDeltaX
of type long
, readonlywheelDeltaY
of type long
, readonlywheelDeltaZ
of type long
, readonlyinitMouseMultiWheelEventNS
MouseMultiWheelEvent
object. This method has the same behavior as MouseEvent.initMouseEventNS()
.
namespaceURIArg
of type DOMString
UIEvent.initUIEventNS()
method for a description of this parameter.typeArg
of type DOMString
UIEvent.initUIEventNS()
method for a description of this parameter.canBubbleArg
of type boolean
UIEvent.initUIEventNS()
method for a description of this parameter.cancelableArg
of type boolean
UIEvent.initUIEventNS()
method for a description of this parameter.viewArg
of type views::AbstractView
UIEvent.initUIEventNS()
method for a description of this parameter.detailArg
of type long
UIEvent.initUIEventNS()
method for a description of this parameter.screenXArg
of type long
MouseEvent.initMouseEventNS()
method for a description of this parameter.screenYArg
of type long
MouseEvent.initMouseEventNS()
method for a description of this parameter.clientXArg
of type long
MouseEvent.initMouseEventNS()
method for a description of this parameter.clientYArg
of type long
MouseEvent.initMouseEventNS()
method for a description of this parameter.buttonArg
of type unsigned short
MouseEvent.initMouseEventNS()
method for a description of this parameter.relatedTargetArg
of type EventTarget
MouseEvent.initMouseEventNS()
method for a description of this parameter.modifiersListArg
of type DOMString
MouseEvent.initMouseEventNS()
method for a description of this parameter.wheelDeltaXArg
of type long
MouseMultiWheelEvent.wheelDeltaX
.wheelDeltaYArg
of type long
MouseMultiWheelEvent.wheelDeltaY
.wheelDeltaZArg
of type long
MouseMultiWheelEvent.wheelDeltaZ
.Type | mousemultiwheel |
---|---|
Namespace | None |
Interface | MouseMultiWheelEvent |
Cancelable | Yes |
Bubbles | Yes |
Target | Document , Element |
Context info | MouseMultiWheelEvent.wheelDeltaX , MouseMultiWheelEvent.wheelDeltaY , MouseMultiWheelEvent.wheelDeltaZ , 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. |
mousewheel
event iff it supports that event type and MouseMultiWheelEvent.wheelDeltaY
is non-zero.This module defines the feature MouseWheelEvents 3.0 and depends on the feature MouseEvents 3.0.
Mouse wheel events are a subset of mouse multi wheel events. See Mouse multi wheel event types for additional information.
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.
// 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); };
wheelDelta
of type long
, readonlyinitMouseWheelEventNS
MouseWheelEvent
object. This method has the same behavior as MouseEvent.initMouseEventNS()
.
namespaceURIArg
of type DOMString
UIEvent.initUIEventNS()
method for a description of this parameter.typeArg
of type DOMString
UIEvent.initUIEventNS()
method for a description of this parameter.canBubbleArg
of type boolean
UIEvent.initUIEventNS()
method for a description of this parameter.cancelableArg
of type boolean
UIEvent.initUIEventNS()
method for a description of this parameter.viewArg
of type views::AbstractView
UIEvent.initUIEventNS()
method for a description of this parameter.detailArg
of type long
UIEvent.initUIEventNS()
method for a description of this parameter.screenXArg
of type long
MouseEvent.initMouseEventNS()
method for a description of this parameter.screenYArg
of type long
MouseEvent.initMouseEventNS()
method for a description of this parameter.clientXArg
of type long
MouseEvent.initMouseEventNS()
method for a description of this parameter.clientYArg
of type long
MouseEvent.initMouseEventNS()
method for a description of this parameter.buttonArg
of type unsigned short
MouseEvent.initMouseEventNS()
method for a description of this parameter.relatedTargetArg
of type EventTarget
MouseEvent.initMouseEventNS()
method for a description of this parameter.modifiersListArg
of type DOMString
MouseEvent.initMouseEventNS()
method for a description of this parameter.wheelDeltaArg
of type long
MouseWheelEvent.wheelDelta
.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. |
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.
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.
// 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); };
An integer indicating in which way the Attr
was changed.
ADDITION
Attr
was just added.MODIFICATION
Attr
was modified in place.REMOVAL
Attr
was just removed.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.initMutationEvent
MutationEvent
object. This method has the same behavior as Event.initEvent()
.
typeArg
of type DOMString
Event.initEvent()
method for a description of this parameter.canBubbleArg
of type boolean
Event.initEvent()
method for a description of this parameter.cancelableArg
of type boolean
Event.initEvent()
method for a description of this parameter.relatedNodeArg
of type Node
MutationEvent.relatedNode
.prevValueArg
of type DOMString
MutationEvent.prevValue
. This value may be null.newValueArg
of type DOMString
MutationEvent.newValue
. This value may be null.attrNameArg
of type DOMString
MutationEvent.attrName
. This value may be null.attrChangeArg
of type unsigned short
MutationEvent.attrChange
. This value may be null.initMutationEventNS
introduced in DOM Level 3MutationEvent
object. This method has the same behavior as Event.initEventNS()
.
namespaceURIArg
of type DOMString
Event.initEventNS()
method for a description of this parameter.typeArg
of type DOMString
Event.initEventNS()
method for a description of this parameter.canBubbleArg
of type boolean
Event.initEventNS()
method for a description of this parameter.cancelableArg
of type boolean
Event.initEventNS()
method for a description of this parameter.relatedNodeArg
of type Node
MutationEvent.initMutationEvent()
method for a description of this parameter.prevValueArg
of type DOMString
MutationEvent.initMutationEvent()
method for a description of this parameter.newValueArg
of type DOMString
MutationEvent.initMutationEvent()
method for a description of this parameter.attrNameArg
of type DOMString
MutationEvent.initMutationEvent()
method for a description of this parameter.attrChangeArg
of type unsigned short
MutationEvent.initMutationEvent()
method for a description of this parameter.The mutation event types are listed below.
Type | DOMSubtreeModified |
---|---|
Namespace | None |
Interface | MutationEvent |
Cancelable | No |
Bubbles | Yes |
Target | Document , DocumentFragment , Element , Attr |
Context info | None |
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. |
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.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. |
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.Type | DOMNodeRemovedFromDocument |
---|---|
Namespace | None |
Interface | MutationEvent |
Cancelable | No |
Bubbles | Yes |
Target | Element , Attr , Text , Comment , CDATASection , DocumentType , EntityReference , ProcessingInstruction |
Context info | None |
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.Type | DOMNodeInsertedIntoDocument |
---|---|
Namespace | None |
Interface | MutationEvent |
Cancelable | No |
Bubbles | Yes |
Target | Element , Attr , Text , Comment , CDATASection , DocumentType , EntityReference , ProcessingInstruction |
Context info | None |
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.Type | DOMAttrModified |
---|---|
Namespace | None |
Interface | MutationEvent |
Cancelable | No |
Bubbles | Yes |
Target | Element |
Context info | MutationEvent.attrName and MutationEvent.attrChange are in use. The value of MutationEvent.relatedNode indicates the Attr node that has been modified, added, or removed. If the Attr node has been added, MutationEvent.newValue is in use. If the Attr node has been removed, MutationEvent.prevValue is in use. If the Attr node has been modified, MutationEvent.newValue and MutationEvent.prevValue are in use. |
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
.Type | DOMCharacterDataModified |
---|---|
Namespace | None |
Interface | MutationEvent |
Cancelable | No |
Bubbles | Yes |
Target | Text , Comment , CDATASection , ProcessingInstruction |
Context info | MutationEvent.prevValue , and MutationEvent.newValue are in use. |
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.This module defines the feature MutationNameEvents 3.0 and depends on the features MutationEvents 3.0 and Core 3.0.
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.
// 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); };
prevNamespaceURI
of type DOMString
, readonlyrelatedNode
's namespaceURI
.prevNodeName
of type DOMString
, readonlyrelatedNode
's nodeName
.initMutationNameEvent
introduced in DOM Level 3MutationNameEvent
object. This method has the same behavior as MutationEvent.initMutationEvent()
.
typeArg
of type DOMString
MutationEvent.initMutationEvent()
method for a description of this parameter.canBubbleArg
of type boolean
MutationEvent.initMutationEvent()
method for a description of this parameter.cancelableArg
of type boolean
MutationEvent.initMutationEvent()
method for a description of this parameter.relatedNodeArg
of type Node
MutationEvent.initMutationEvent()
method for a description of this parameter.prevNamespaceURIArg
of type DOMString
MutationNameEvent.prevNamespaceURI
. This value may be null
.prevNodeNameArg
of type DOMString
MutationNameEvent.prevNodeName
.initMutationNameEventNS
introduced in DOM Level 3MutationNameEvent
object. This method has the same behavior as MutationEvent.initMutationEventNS()
.
namespaceURIArg
of type DOMString
MutationEvent.initMutationEventNS()
method for a description of this parameter.typeArg
of type DOMString
MutationEvent.initMutationEventNS()
method for a description of this parameter.canBubbleArg
of type boolean
MutationEvent.initMutationEventNS()
method for a description of this parameter.cancelableArg
of type boolean
MutationEvent.initMutationEventNS()
method for a description of this parameter.relatedNodeArg
of type Node
MutationEvent.initMutationEventNS()
method for a description of this parameter.prevNamespaceURIArg
of type DOMString
MutationEvent.initMutationEvent()
method for a description of this parameter.prevNodeNameArg
of type DOMString
MutationEvent.initMutationEvent()
method for a description of this parameter.The mutation name event types are listed below.
Type | DOMElementNameChanged |
---|---|
Namespace | None |
Interface | MutationNameEvent |
Cancelable | No |
Bubbles | Yes |
Target | Element |
Context info | MutationNameEvent.prevNamespaceURI , and MutationNameEvent.prevNodeName are in use. |
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.Type | DOMAttributeNameChanged |
---|---|
Namespace | None |
Interface | MutationNameEvent |
Cancelable | No |
Bubbles | Yes |
Target | Element |
Context info | MutationNameEvent.prevNamespaceURI , and MutationNameEvent.prevNodeName are in use. The value of MutationEvent.relatedNode contains the renamed Attr node. |
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.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.
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. |
Document
node.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. |
Document
node.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. |
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. |
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. |
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. |
Type | resize |
---|---|
Namespace | None |
Interface | UIEvent |
Cancelable | No |
Bubbles | Yes |
Target | Document , Element |
Context info | UIEvent.view is in use. |
Type | scroll |
---|---|
Namespace | None |
Interface | UIEvent |
Cancelable | No |
Bubbles | Yes |
Target | Document , Element |
Context info | UIEvent.view is in use. |