/
index-snapshot.html
10921 lines (9940 loc) · 542 KB
/
index-snapshot.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>UI Events Specification</title>
<link rel="author" href="mailto:www-dom@w3.org" />
<link rel="help" href="http://www.w3.org/DOM/" />
<link rel="alternate stylesheet" type="text/css" media="screen" title="geek" href="geek.css" />
<link rel="stylesheet" type="text/css" href="spec-WD.css" />
<link rel="stylesheet" type="text/css" href="https://www.w3.org/StyleSheets/TR/w3c-tr.css" />
<link rel="stylesheet" type="text/css" href="https://www.w3.org/StyleSheets/TR/W3C-WD" />
<link rel="stylesheet" type="text/css" href="override.css" />
<style>
.tblstyle { border: 0; border-collapse: collapse; }
</style>
<script type="text/javascript" src='https://www.w3.org/Tools/respec/respec-w3c-common' class='remove' async></script>
<script type="text/javascript" src='fixup.js'></script>
<script type="text/javascript">
var respecConfig = {
specStatus: "ED",
shortName: "uievents",
editors: [
{
name: "Gary Kacmarcik",
company: "Google, Inc.",
url: "mailto:garykac@google.com?subject=%5BUI-events%5D%20Spec%20Feedback",
companyURL: "http://www.google.com",
note: "since Jun 2013",
},
{
name: "Travis Leithead",
company: "Microsoft Corp.",
url: "mailto:travis.leithead@microsoft.com?subject=%5BUI-events%5D%20Spec%20Feedback",
companyURL: "http://www.microsoft.com",
note: "since Feb 2012",
}
],
publishDate: "2016-01-19",
edDraftURI: "https://w3c.github.io/uievents/",
previousPublishDate: "2015-03-19",
previousMaturity: "WD",
noIDLIn: true,
inlineCSS: true,
//noRecTrack: true, //test
wg: ["Web Platform Working Group"],
wgURI: ["http://www.w3.org/WebPlatform/WG/"],
license: "w3c-software-doc",
wgPublicList: "www-dom",
wgPatentURI: ["http://www.w3.org/2004/01/pp-impl/83482/status"],
maxTocLevel: 3,
otherLinks: [{
key: 'Participate',
data: [{
value: 'We are on Github',
href: 'https://github.com/w3c/uievents',
}, {
value: 'Issues list (bugs)',
href: 'https://github.com/w3c/uievents/issues',
}, {
value: 'File a bug',
href: 'https://github.com/w3c/uievents/issues/new',
}, {
value: 'Commit history',
href: 'https://github.com/w3c/uievents/commits',
}, {
value: 'Mailing list archive (www-dom)',
href: 'http://lists.w3.org/Archives/Public/www-dom/',
}],
}],
};
</script>
</head>
<body>
<!-- Section: Abstract ========================================================-->
<section id="abstract">
<p>This specification defines UI Events which extend the DOM Event objects defined in
[<a href="#references-DOM4">DOM4</a>]. UI Events are those typically implemented by
visual user agents for handling user interaction such as mouse and keyboard input.
</p>
</section> <!-- abstract -->
<!-- Section: SOTD ========================================================-->
<section id="sotd">
<p>This document is a Working Draft of the UI Events specification.
It is expected that this specification will progress to
<abbr title="World Wide Web Consortium">W3C</abbr>
Recommendation status after review and refinement.
</p>
<p id="this-document-is-produced-by-the-web-app">
This document is produced by the
<a href="http://www.w3.org/WebPlatform/WG/">Web Platform Working Group</a>,
part of the
<a href="http://www.w3.org/2006/rwc/Activity">Rich Web Clients Activity</a>
in the W3C
<a href="http://www.w3.org/Interaction/">Interaction Domain</a>.
It is expected that this document will progress along the W3C's Recommendation track.
Publication as a Working Draft does not imply endorsement by the W3C Membership.
This is a draft document and MAY be updated, replaced or obsoleted by other
documents at any time.
It is inappropriate to cite this document as other than work in progress.
</p>
<p>This document is derived from the specification known as Document Object Model Events
Level 3, which in turn builds on the Document Object Model Events Level 2 specification
[<a href="#references-DOM2Events">DOM2 Events</a>].
</p>
<p id="unstable">
<strong class="redNote">Implementers should be aware that this document is not stable.</strong>
Implementers who are not taking part in the discussions are likely to find the
specification changing out from under them in incompatible ways.
Vendors interested in implementing this document before it eventually reaches
the Candidate Recommendation stage should join the aforementioned mailing lists
and take part in the discussions.
</p>
</section> <!-- sotd -->
<!-- Section 1: UI Events Overview ========================================================-->
<section id="dom-events-intro">
<h1>Introduction</h1>
<section id="dom-events-overview">
<h2>Overview</h2>
<p>DOM Events is designed with two main goals. The first goal is the design of an <a class="def" href="#glossary-event">event</a> 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.</p>
<p>The second goal of DOM Events is to provide a common subset of the current event systems used in existing 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.</p>
</section> <!-- dom-events-overview -->
<section id="dom-events-conformance">
<h2>Conformance</h2>
<p><strong>This section is normative.</strong></p>
<p>Within this specification, the key words <q>MUST</q>, <q>MUST NOT</q>, <q>REQUIRED</q>,
<q>SHALL</q>, <q>SHALL NOT</q>, <q>SHOULD</q>, <q>SHOULD NOT</q>,
<q>RECOMMENDED</q>, <q>MAY</q>, and <q>OPTIONAL</q> are to be interpreted as described in
[<a href="#RFC2119">RFC2119</a>].</p>
<p>This specification is to be understood in the context of the DOM Level 3 Core specification
[<cite><a class="normative" href="#references-DOMCore">DOM3 Core</a></cite>] and the general
considerations for DOM implementations apply.
For example, handling of <a class="def" href="#glossary-namespaceURI">namespace URIs</a> is discussed in
<a class="normative" href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#Namespaces-Considerations"><em>XML Namespaces</em></a>.
For additional information about
<a class="normative" href="http://www.w3.org/TR/DOM-Level-3-Core/introduction.html#ID-Conformance"><em>conformance</em></a>,
please see the DOM Level 3 Core specification
[<cite><a class="normative" href="#references-DOMCore">DOM3 Core</a></cite>].
A <a class="def" href="#glossary-user-agent">user agent</a> is not required to conform
to the entirety of another specification in order to conform to this specification, but it MUST
conform to the specific parts of any other specification which are called out in this specification
(e.g., a conforming UI Events <a class="def" href="#glossary-user-agent">user agent</a> MUST support
the <code>DOMString</code> data type as defined in <a href="#references-WebIDL">Web IDL</a>, but need
not support every method or data type defined in <a href="#references-WebIDL">Web IDL</a> in order to
conform to UI Events).
</p>
<p>This specification defines several classes of conformance for different
<a class="def" href="#glossary-user-agent">user agents</a>, specifications, and content authors:
</p>
<dl>
<dt id="conf-interactive-ua">Web browsers and other dynamic or interactive
<a class="def" href="#glossary-user-agent">user agents</a>
</dt>
<dd>
<p>A dynamic or interactive <a class="def" href="#glossary-user-agent">user agent</a>, referred to
here as a <q>browser</q> (be it a Web browser, AT (Accessibility Technology) application,
or other similar program), conforms to UI Events if it supports:
</p>
<ul>
<li>the Core module defined in
[<cite><a class="normative" href="#references-DOMCore">DOM3 Core</a></cite>]
</li>
<li>the <a href="#event-flow">Event dispatch and DOM event flow</a> mechanism
</li>
<li>all the interfaces and events with their associated methods, attributes, and
semantics defined in this specification with the exception of those marked as
<a class="def" href="#glossary-deprecated">deprecated</a> (a conforming user
agent MAY implement the deprecated interfaces, events, or APIs for backwards
compatibility, but is not required to do so in order to be conforming)
</li>
<li>the complete set of <code>key</code> and <code>code</code> values defined in
[<a href="#references-D3E-key">DOM3 key Values</a>] and
[<a href="#references-D3E-code">DOM3 code Values</a>]
(subject to platform availability), and
</li>
<li>all other normative requirements defined in this specification.
</li>
</ul>
<p>A conforming browser MUST <a class="def" href="#glossary-dispatch">dispatch</a> events appropriate
to the given <a href="#interface-EventTarget">EventTarget</a> when the conditions defined
for that <a class="def" href="#glossary-event-type">event type</a> have been met.
</p>
<p>A browser conforms specifically to UI Events if it implements
the interfaces and related <a class="def" href="#glossary-event-type">event types</a>
specified in <a href="#event-types">Event Types</a>.
</p>
<p>A conforming browser MUST support scripting, declarative interactivity, or some other means of
detecting and dispatching events in the manner described by this specification, and MUST support
the APIs specified for that <a class="def" href="#glossary-event-type">event type</a>.
</p>
<p>In addition to meeting all other conformance criteria, a conforming browser MAY implement
features of this specification marked as
<a class="def" href="#glossary-deprecated">deprecated</a>, for backwards compatibility with
existing content, but such implementation is discouraged.
</p>
<p>A conforming browser MAY also support features not found in this specification, but which use
the <a href="#event-flow">Event dispatch and DOM event flow</a> mechanism, interfaces, events,
or other features defined in this specification, and MAY implement additional interfaces and
<a class="def" href="#glossary-event-type">event types</a> appropriate to that implementation.
Such features can be later standardized in future specifications.
</p>
<p>A browser which does not conform to all required portions of this specification MUST NOT claim
conformance to UI Events.
Such an implementation which does conform to portions of this specification MAY claim
conformance to those specific portions.
</p>
<p>A conforming browser MUST also be a <i>conforming implementation</i> of the IDL fragments in this
specification, as described in the Web IDL specification <a href="#references-WebIDL">[WEBIDL]</a>.
</p>
</dd>
<dt id="conf-author-tools">Authoring tools</dt>
<dd>
<p>A content authoring tool conforms to UI Events if it produces content which uses the
<a class="def" href="#glossary-event-type">event types</a> and
<a href="#event-flow">Event dispatch and DOM event flow</a> model, consistent in a manner as
defined in this specification.
</p>
<p>A content authoring tool MUST NOT claim conformance to UI Events for content it produces
which uses features of this specification marked as
<a class="def" href="#glossary-deprecated">deprecated</a> in this specification.
</p>
<p>A conforming content authoring tool SHOULD provide to the content author a means to use all
<a class="def" href="#glossary-event-type">event types</a> and interfaces appropriate to all
<a class="def" href="#glossary-host-language">host languages</a> in the content document being
produced.
</p>
</dd>
<dt id="conf-authors">Content authors and content</dt>
<dd>
<p>A content author creates conforming UI Events content if that content uses the
<a class="def" href="#glossary-event-type">event types</a> and
<a href="#event-flow">Event dispatch and DOM event flow</a> model, consistent in a manner as
defined in this specification.
</p>
<p>A content author SHOULD NOT use features of this specification marked as
<a class="def" href="#glossary-deprecated">deprecated</a>, but SHOULD rely instead upon
replacement mechanisms defined in this specification and elsewhere.
</p>
<p>Conforming content MUST use the semantics of the interfaces and
<a class="def" href="#glossary-event-type">event types</a> as described in this specification.
</p>
<p class="note"><strong>Authoring Note:</strong>
Content authors are advised to follow best practices as described in
<a href="http://www.w3.org/TR/WAI-WEBCONTENT/">accessibility</a> and
<a href="http://www.w3.org/standards/techs/i18n">internationalization</a> guideline
specifications.
</p>
</dd>
<dt id="conf-specs">Specifications and host languages</dt>
<dd>
<p>A specification or <a class="def" href="#glossary-host-language">host language</a> conforms
to UI Events if it references and uses the
<a href="#event-flow">Event dispatch and DOM event flow</a> mechanism, interfaces, events,
or other features defined in [<a href="#references-DOM4">DOM4</a>], and does not extend these
features in incompatible ways.
</p>
<p>A specification or <a class="def" href="#glossary-host-language">host language</a> conforms
specifically to UI Events if it references and uses the interfaces and
related <a class="def" href="#glossary-event-type">event types</a> specified in
<a href="#event-types">Event Types</a>.
A conforming specification MAY define additional interfaces and
<a class="def" href="#glossary-event-type">event types</a> appropriate to that specification,
or MAY extend the UI Events interfaces and
<a class="def" href="#glossary-event-type">event types</a> in a manner that does not contradict
or conflict with the definitions of those interfaces and
<a class="def" href="#glossary-event-type">event types</a> in this specification.
</p>
<p>Specifications or <a class="def" href="#glossary-host-language">host languages</a> which
reference UI Events SHOULD NOT use or recommend features of this
specification marked as <a class="def" href="#glossary-deprecated">deprecated</a>, but
SHOULD use or recommend the indicated replacement for that the feature (if available).
</p>
</dd>
</dl>
</section> <!-- dom-events-conformance -->
<section id="style-conventions">
<h2>Stylistic Conventions</h2>
<p>This specification follows the <a href="http://www.w3.org/People/Schepers/spec-conventions.html">Proposed W3C Specification
Conventions</a>, with the following supplemental additions:</p>
<dl>
<dt>Key and character values</dt>
<dd><ul>
<li>Names of key values are shown as: <code class="key">'='</code> (e.g., the value of
<a href="#widl-KeyboardEvent-key"><code>KeyboardEvent.key</code></a>).
</li>
<li>Names of key codes are shown as: <code class="code">'Equal'</code> (e.g., the value of
<a href="#widl-KeyboardEvent-code"><code>KeyboardEvent.code</code></a>).
</li>
<li>Character values of keys are shown as: <code class="char">'\u003d'</code> (e.g., the code point
of the key value).
</li>
<li>Glyphs representing character values are shown as: <code class="glyph">'='</code> (e.g., the
<a href="#key-legends"><em>key cap</em></a> or font associated with a character value).
</li>
</ul></dd>
</dl>
<p>In addition, certain terms are used in this specification with particular meanings. The term <q>implementation</q> applies to a browser, content authoring tool,
or other <a class="def" href="#glossary-user-agent">user agent</a> that implements this specification, while a content author is a person who writes script or code
that takes advantage of the interfaces, methods, attributes, events, and other features described in this specification in order to make Web applications, and a
user is the person who uses those Web applications in an implementation.</p>
</section> <!-- style-conventions -->
</section> <!-- dom-events-intro -->
<!-- Section 2: Issues ==============================================================-->
<section id="issues">
<h1>Issues</h1>
<p class="issue">Open issues in this specification are called out using this convention.</p>
</section>
<!-- Section 3: Architecture ========================================================-->
<section id="dom-event-architecture">
<h1>DOM Event Architecture</h1>
<p><em>This section is informative.</em></p>
<section id="event-flow">
<h2>Event dispatch and DOM event flow</h2>
<p>This section defines the event <a class="def" href="#glossary-dispatch">dispatch</a> mechanism of the event model defined in this specification.
Applications MAY dispatch event objects using the <a href="#widl-EventTarget-dispatchEvent"><code>EventTarget.dispatchEvent()</code></a> method, and
implementations MUST dispatch event objects as if through this method. The behavior of this method depends on the <em>event flow</em>
associated with the underlying object. An event flow describes how event objects <em>propagate</em> 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.</p>
<figure id="figure-dom-event-flow">
<img src='images/eventflow.svg' height="560" alt="Graphical representation of an event dispatched in a DOM tree using the DOM event flow"/>
<figcaption>Graphical representation of an event dispatched in a DOM tree using the DOM event flow</figcaption>
</figure>
<p>Event objects are dispatched to an <a class="def" href="#glossary-event-target">event target</a>. At the beginning
of the dispatch, implementations MUST first determine the event object's <a class="def" href="#glossary-propagation-path">propagation path</a>.</p>
<p>The propagation path MUST be an ordered list of <a class="def" href="#glossary-current-event-target">current event targets</a> through which
the event object MUST pass. For DOM implementations, the propagation path MUST reflect the hierarchical tree
structure of the document. The last item in the list MUST be the <a class="def" href="#glossary-event-target">event target</a>. The
preceding items in the list are referred to as the <em>target's ancestors</em>, and the immediately preceding item as the <em>target's parent</em>. Once determined, the
propagation path MUST NOT be changed. For DOM implementations, this applies even if an element in the propagation path is moved within the
DOM or removed from the DOM.</p>
<div class="example">
<div class="example-title"></div>
<p>In the DOM event flow, event listeners might change the position of the <a class="def" href="#glossary-event-target">
event target</a> in the document while the event object is being dispatched. Such changes do not affect the propagation path.</p>
</div>
<p>Note that event listeners are not copied over when <code>Node</code> are copied using methods such as
<code>Node.cloneNode</code> or <code>Range.cloneContents</code>
[<cite><a class="informative" href="#references-DOMRange">DOM Range</a></cite>].
</p>
<p>Exceptions thrown inside event listeners MUST NOT stop the propagation of the event or affect the
<a class="def" href="#glossary-propagation-path">propagation path</a>. The exception itself MUST NOT propagate outside the scope of the event
handler.</p>
<div class="example">
<div class="example-title"></div>
<p>In the following code, the exception thrown from the call to <code>throw "Error"</code> does not propagate into the parent scope
(which would prevent the <code>console.log</code> statement from executing):</p>
<pre>var e = document.createEvent("Event");
e.initEvent("myevent", false, false);
var target = document.createElement("div");
target.addEventListener("myevent", function () {
throw "Error";
});
target.dispatchEvent(e); <span class="comment">// Causes the event listener to throw an exception...</span>
<span class="comment">// The previously thrown exception doesn't affect the code that follows:</span>
console.log("Exceptions? No problem");</pre>
</div>
<p id="event-phase">As the next step, the event object MUST complete one or more <a class="def" href="#glossary-phase">event phases</a>. This specification defines
three event phases: <a href="#capture-phase">capture phase</a>, <a href="#target-phase">target phase</a> and <a href="#bubble-phase">bubble phase</a>. Event objects
complete these phases in the specified order using the partial propagation paths as defined below. A phase MUST be skipped if it is not
supported, or if the event object's propagation has been stopped. For example, if the <a href="#widl-Event-bubbles"><code>Event.bubbles</code></a>
attribute is set to false, the bubble phase will be skipped, and if <a href="#widl-Event-stopPropagation"><code>Event.stopPropagation()</code></a> has been
called prior to the dispatch, all phases MUST be skipped.</p>
<ol>
<li>The <strong id="capture-phase">capture phase</strong>: The event object MUST propagate through the target's ancestors from the <a class="def"
href="#glossary-window">Window</a> to the target's parent. This phase is also known as the <em>capturing phase</em>. Event
listeners registered for this phase MUST handle the event before it reaches its target.</li>
<li>The <strong id="target-phase">target phase</strong>: The event object MUST arrive at the event object's <a class="def" href="#glossary-event-target">
event target</a>. This phase is also known as the <em>at-target phase</em>. Event listeners registered for this phase MUST
handle the event once it has reached its target. If the <a class="def" href="#glossary-event-type">event type</a> indicates that
the event MUST NOT bubble, the event object MUST halt after completion of this phase.</li>
<li>The <strong id="bubble-phase">bubble phase</strong>: The event object propagates through the target's ancestors in reverse order, starting
with the target's parent and ending with the <a class="def" href="#glossary-window">Window</a>. This phase is also known as the <em>bubbling phase</em>.
Event listeners registered for this phase MUST handle the event after it has reached its target.</li>
</ol>
<p>Implementations MUST 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 <a href="#widl-Event-stopPropagation"><code>
Event.stopPropagation()</code></a>.</p>
<p>First, the implementation MUST determine the <em>current target</em>. This MUST be the next pending event target in the partial propagation
path, starting with the first. From the perspective of an event listener this MUST be the event target the listener has been registered on.</p>
<p>Next, the implementation MUST determine the current target's <a class="def" href="#glossary-candidate-event-handlers">candidate event listeners</a>.
This MUST be the list of all event listeners that have been registered on the current target in their order of registration. [<cite><a class="informative"
href="#references-HTML5">HTML5</a></cite>] defines the ordering of listeners registered through event handler attributes. Once determined, the candidate event listeners
MUST NOT be changed. Adding or removing listeners does not affect the current target's candidate event listeners.</p>
<p>Finally, the implementation MUST process all candidate <a class="def" href="#glossary-event-handler">event handlers</a> in order and trigger
each handler if all the following conditions are met:</p>
<ul>
<li>The event object's immediate propagation has not been stopped.</li>
<li>The listener has been registered for this event phase.</li>
<li>The listener has been registered for this <a class="def" href="#glossary-event-type">event type</a>.</li>
</ul>
<p>In the production of the <a class="def" href="#glossary-propagation-path">propagation path</a>, the event propagates from the <a class="def" href="#glossary-window">Window</a>
to the <code>document</code> object during the <a class="def" href="#glossary-capture-phase">capture phase</a>, and from the <code>document</code> object to the
<a class="def" href="#glossary-window">Window</a> during the <a class="def" href="#glossary-bubbling-phase">bubble phase</a>.</p>
<p>After an event completes all the phases of its <a class="def" href="#glossary-propagation-path">propagation path</a>, its <a href="#widl-Event-currentTarget">
<code>Event.currentTarget</code></a> MUST be set to <code>null</code> and the <a href="#widl-Event-eventPhase"><code>Event.eventPhase</code></a> MUST be
set to <code>0</code> (<a href="#widl-Event-NONE"><code>NONE</code></a>). All other attributes of the <code>Event</code> (or interface derived from <code>Event</code>)
are unchanged (including the <a href="#widl-Event-target"><code>Event.target</code></a> attribute, which MUST continue to reference the <a class="def" href="#glossary-event-target">
event target</a>).</p>
<p>The model defined above MUST be applied regardless of the specific event flow associated with an event target. Each event flow MUST define how the propagation path
MUST be determined and which event phases are supported. The <em>DOM event flow</em> is an application of this model: the propagation path for a <code>Node</code>
object MUST be determined by its <code>Node.parentNode</code> chain, and if applicable, the document's containing <a class="def" href="#glossary-window">Window</a>.
All events accomplish the capture and target phases. Whether an event accomplishes the bubble phase MUST be defined individually for each <a class="def" href="#glossary-event-type">
event type</a>. An alternate application of this model can be found in [<cite><a class="informative" href="#references-DOMLS">DOM3 Load and Save</a></cite>].</p>
<p>Implementations of the DOM event model MUST be 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 MUST resume only after the event dispatch of the new event is completed.</p>
</section> <!-- event-flow -->
<section id="event-flow-default-cancel">
<h2>Default actions and cancelable events</h2>
<p>Events are typically dispatched by the implementation as a result of a user action, in response to the completion of a task, or to signal progress during asynchronous
activity (such as a network request). Some events can be used to control the behavior that the implementation MAY take next (or undo an action that the implementation
already took). Events in this category are said to be <em>cancelable</em> and the behavior they cancel is called their <a class="def" href="#glossary-default-action">
<em>default action</em></a>. Cancelable event objects can be associated with one or more <a class="def" href="#glossary-default-action">default actions</a>.
To cancel an event, call the <a href="#widl-Event-preventDefault"><code>Event.preventDefault()</code></a> method.</p>
<div class="example">
<div class="example-title"></div>
<p>A <a class="eventtype" href="#event-type-mousedown"><code>mousedown</code></a> event is dispatched immediately after the user presses down a button on a
pointing device (typically a mouse). One possible <a class="def" href="#glossary-default-action">default action</a> taken by the implementation is to set up a state
machine that allows the user to drag images or select text. The <a class="def" href="#glossary-default-action">default action</a> depends on what happens next — for
example, if the user's pointing device is over text, a text selection might begin. If the user's pointing device is over an image, then an image-drag action could
begin. Preventing the <a class="def" href="#glossary-default-action">default action</a> of a <a class="eventtype" href="#event-type-mousedown"><code>mousedown</code></a>
event prevents these actions from occurring.</p>
</div>
<p><a class="def" href="#glossary-default-action">Default actions</a> SHOULD be performed after the event dispatch has been completed, but in exceptional
cases MAY also be performed immediately before the event is dispatched.</p>
<div class="example">
<div class="example-title"></div>
<p>The default action associated with the <a class="eventtype" href="#event-type-click"><code>click</code></a> event on <code><input
type="checkbox"></code> elements toggles the <code>checked</code> IDL attribute value of that element. If the <a class="eventtype" href="#event-type-click"><code>click</code>
</a> event's default action is cancelled, then the value is restored to its former state.</p>
</div>
<p id="events-dt-cancelable-event">When an event is canceled, then the conditional <a class="def" href="#glossary-default-action">default actions</a> associated with the event MUST be skipped (or
as mentioned above, if the <a class="def" href="#glossary-default-action">default actions</a> are carried out before the dispatch, their effect MUST be undone).
Whether an event object is cancelable MUST be indicated by the <a href="#widl-Event-cancelable"><code>Event.cancelable</code></a> attribute. <a href="#widl-Event-preventDefault">
<code>Event.preventDefault()</code></a> stops all related <a class="def" href="#glossary-default-action">default actions</a> of an event object. The <a href="#widl-Event-defaultPrevented">
<code>Event.defaultPrevented</code></a> attribute indicates whether an event has already been canceled (e.g., by a prior event listener). If the <a class="def" href="#glossary-DOM-application">
DOM application</a> itself initiated the dispatch, then the return value of the <a href="#widl-EventTarget-dispatchEvent"><code>EventTarget.dispatchEvent()</code></a>
method indicates whether the event object was cancelled.</p>
<p class="note"><strong>Authoring Note: </strong>Many implementations additionally interpret an event listener's return value, such as the value <code>false</code>, to mean
that the <a class="def" href="#glossary-default-action">default action</a> of cancelable events will be cancelled (though <code>window.onerror</code> handlers are cancelled
by returning <code>true</code>).</p>
<p class="note"><strong>Authoring Note: </strong>Some cancelable events might not have any observable <a class="def" href="#glossary-default-action">default actions</a>. For
example, the <a class="eventtype" href="#event-type-mousemove"><code>mousemove</code></a> event.</p>
<p>This specification does not offer features to programatically query if an event object has any <a class="def" href="#glossary-default-action">default action</a> associated with
it, or to associate new <a class="def" href="#glossary-default-action">default actions</a> with an event object. Other specifications SHOULD define what default actions, if any,
are associated with certain event objects. Further, implementations MAY associate <a class="def" href="#glossary-default-action">default actions</a> with events as necessary and
appropriate for that implementation.</p>
<div class="example">
<div class="example-title"></div>
<p>As an example, one implementation might scroll a document view by a certain amount as the <a class="def" href="#glossary-default-action">
default action</a> of a <a class="eventtype" href="#event-type-wheel"><code>wheel</code></a> event, while another implementation might instead zoom the document as its <a class="def"
href="#glossary-default-action">default action</a>.</p>
</div>
</section> <!-- event-flow-default-cancel -->
<section id="sync-async">
<h2>Synchronous and asynchronous events</h2>
<p>Events MAY be dispatched either synchronously or asynchronously.</p>
<p>Events which are synchronous (<em><q>sync events</q></em>) MUST be treated as if they are in a virtual queue in a first-in-first-out model, ordered by sequence
of temporal occurrence with respect to other events, to changes in the DOM, and to user interaction. Each event in this virtual queue MUST be delayed until the
previous event has completed its propagation behavior, or been canceled. Some sync events are driven by a specific device or process, such as mouse button events.
These events are governed by the <a class="def" href="#glossary-event-order">event order</a> algorithms defined for that set of events, and a user agent MUST dispatch
these events in the defined order.</p>
<div class="example">
<div class="example-title"></div>
<p>A user double-clicks a passage of text to select a word, then presses the <code class="key">'Delete'</code>
key to erase the word, triggering the following synchronous sequence of events:
<a class="eventtype" href="#event-type-mousedown"><code>mousedown</code></a>,
<a class="eventtype" href="#event-type-mouseup"><code>mouseup</code></a>,
<a class="eventtype" href="#event-type-click"><code>click</code></a>,
<a class="eventtype" href="#event-type-mousedown"><code>mousedown</code></a>,
<a class="eventtype" href="#event-type-mouseup"><code>mouseup</code></a>,
<a class="eventtype" href="#event-type-click"><code>click</code></a>,
<a class="eventtype" href="#event-type-dblclick"><code>dblclick</code></a>,
<a class="eventtype" href="#event-type-select"><code>select</code></a>,
<a class="eventtype" href="#event-type-keydown"><code>keydown</code></a>,
<a class="eventtype" href="#event-type-beforeinput"><code>beforeinput</code></a>,
<a class="eventtype" href="#event-type-input"><code>input</code></a>,
<a class="eventtype" href="#event-type-keyup"><code>keyup</code></a>.
Each of these events are fired in the sequence initiated by the user's actions.</p>
</div>
<p>Events which are asynchronous (<em><q>async events</q></em>) MAY be dispatched as the results of the action are completed, with no relation to other events, to
other changes in the DOM, nor to user interaction.</p>
<div class="example">
<div class="example-title"></div>
<p>During loading of a document, an inline script element is parsed and executed. The <a class="eventtype" href="#event-type-load">
<code>load</code></a> event is queued to be fired asynchronously at the script element. However, because it is an async event, its order with relation to other synchronous
events fired during document load (such as the <code class="eventtype">DOMContentLoaded</code> event from <cite><a class="informative" href="#references-HTML5">HTML5</a></cite>) is not guaranteed.</p>
</div>
<section id="event-order-and-loops">
<h3>Event order and event loops</h3>
<p>Most events take place in a sequential context. [<cite><a class="informative" href="#references-HTML5">HTML5</a></cite>] defines its event operations in terms
of an event loop mechanism, in which events of all types are fed into different <em>task queues</em>. This specification does not define events in terms of this
event loop mechanism, but it is compatible with this mechanism. Instead, this specification defines several operation-specific <a class="def" href="#glossary-event-order">
event orders</a>.</p>
<p>Using the terminology of HTML5, each independent device, such as a mouse or keyboard, SHOULD be treated as a <em>task source</em> which feeds into the appropriate
<em>task queue</em>, in the order defined by the <a class="def" href="#glossary-event-order">event order</a> associated with that device. Each operation, such as
a focus change or composition input, also acts as a <em>task source</em> for the appropriate <em>task queue</em>. The resolution of these event loops is handled
in a manner conforming to the <a class="def" href="#glossary-host-language">host language</a>, such as HTML [<cite><a class="informative" href="#references-HTML5">HTML5</a></cite>].</p>
<p class="note"><strong>Authoring Note:</strong> Certain events, such as <q>hotkeys</q> or control keys pressed in a certain sequence, can be
<q>swallowed</q> by the operating system or the application, interrupting the expected <a class="def" href="#glossary-event-order">event order</a>.</p>
</section> <!-- event-order-and-loops -->
</section> <!-- sync-async -->
<section id="trusted-events">
<h2>Trusted events</h2>
<p>Events that are generated by the user agent, either as a result of user interaction, or as a direct result of changes to the DOM, are trusted by the user agent
with privileges that are not afforded to events generated by script through the <a href="#widl-DocumentEvent-createEvent"><code>DocumentEvent.createEvent("Event")</code></a>
method, modified using the <a href="#widl-Event-initEvent"><code>Event.initEvent()</code></a> method, or dispatched via the <a href="#widl-EventTarget-dispatchEvent">
<code>EventTarget.dispatchEvent()</code></a> method. The <a href="#widl-Event-isTrusted"><code>isTrusted</code></a> attribute of trusted events has a
value of <code>true</code>, while untrusted events have a <a href="#widl-Event-isTrusted"><code>isTrusted</code></a> attribute value of <code>false</code>.</p>
<p>Most untrusted events SHOULD NOT trigger <a class="def" href="#glossary-default-action">default actions</a>, with the exception of the <a class="eventtype" href="#event-type-click">
<code>click</code></a> event. This event always triggers the <a class="def" href="#glossary-default-action">
default action</a>, even if the <a href="#widl-Event-isTrusted"><code>isTrusted</code></a> attribute is <code>false</code> (this behavior is retained for backward-compatibility).
All other untrusted events MUST behave
as if the <a href="#widl-Event-preventDefault"><code>Event.preventDefault()</code></a> method had been called on that event.</p>
</section> <!-- trusted-events -->
<section id="event-flow-activation">
<h2>Activation triggers and behavior</h2>
<p>Certain <a class="def" href="#glossary-event-target">event targets</a> (such as a link or button element) MAY have associated <a class="def" href="#glossary-activation-behavior">
activation behavior</a> (such a following a link) that implementations perform in response to an <em><a class="def" href="#glossary-activation-trigger">activation
trigger</a></em> (such as clicking a link).</p>
<p>A <a class="def" href="#glossary-host-language">host language</a> SHOULD indicate which, if any, elements have activation behavior, describe appropriate <a class="def"
href="#glossary-activation-trigger">activation triggers</a>, and define the result of that activation behavior. An implementation which supports a <a class="def"
href="#glossary-host-language">host language</a> SHOULD initiate these <a class="def" href="#glossary-activation-behavior">activation behavior</a> when the associated
<a class="def" href="#glossary-activation-trigger">activation trigger</a> occurs.</p>
<div class="example" id="example-activation">
<div class="example-title"></div>
<p>Both HTML and SVG have an <code><a></code> element which indicates a link. Relevant <a
class="def" href="#glossary-activation-trigger">activation triggers</a> for an <code><a></code> element are a <a class="eventtype" href="#event-type-click"><code>
click</code></a> event on the text or image content of the <code><a></code> element, or a <a class="eventtype" href="#event-type-keydown"><code>keydown</code></a>
event with a <a href="#widl-KeyboardEvent-key">key</a> attribute value of <code class="key">'Enter'</code> key when the <code><a></code>
element has focus. The activation behavior for an <code><a></code> element is normally to change the content of the window to the content of the new document,
in the case of external links, or to reposition the current document relative to the new anchor, in the case of internal links.</p>
</div>
<p>An <a class="def" href="#glossary-activation-trigger">activation trigger</a> is a user action or an event which indicates to the implementation that an activation
behavior SHOULD be initiated. User-initiated <a class="def" href="#glossary-activation-trigger">activation triggers</a> include clicking a mouse button on an activatable
element, pressing the <code class="key">'Enter'</code> key when an activatable element has focus, or pressing a key that is somehow
linked to an activatable element (a <q>hotkey</q> or <q>access key</q>) even when that element does not have focus. Event-based <a class="def" href="#glossary-activation-trigger">
activation triggers</a> MAY include timer-based events that activate an element at a certain clock time or after a certain time period has elapsed, progress
events after a certain action has been completed, or many other condition-based or state-based events.</p>
<p>In some cases, a <a class="def" href="#glossary-host-language">host language</a> MAY define attributes or even attribute values which add to or change the native
<a class="def" href="#glossary-activation-trigger">activation trigger</a> or <a class="def" href="#glossary-activation-behavior">activation behavior</a> of an element.
For example, ARIA [<cite><a class="informative" href="#ref-ARIA">ARIA</a></cite>] defines values for the <code class="attr">role</code> attribute that add semantics
to the element to which it is applied, for purposes of enhanced accessibility. In such cases, if the <a class="def" href="#glossary-host-language">host language</a>
does not explicitly define the <a class="def" href="#glossary-activation-trigger">activation trigger</a> or <a class="def" href="#glossary-activation-behavior">activation
behavior</a>, the content author MUST provide the mechanics of the <a class="def" href="#glossary-activation-trigger">activation trigger</a> (via an event listener)
or <a class="def" href="#glossary-activation-behavior">activation behavior</a> (such as calling an ECMAScript function) for that element when applying that attribute
or attribute value.</p>
<section id="click-synthesis">
<h3>Activation event synthesis</h3>
<p>If the instance of the <a class="def" href="#glossary-activation-trigger">activation trigger</a> is not an event of <a class="def" href="#glossary-event-type">event
type</a> <a class="eventtype" href="#event-type-click"><code>click</code></a> (that is, when it does not result from a user's activation of a button or link
using a mouse or equivalent pointing device), the implementation MUST synthesize and dispatch an event of <a class="def" href="#glossary-event-type">event type</a> <a
class="eventtype" href="#event-type-click"><code>click</code></a> as one of the <a class="def" href="#glossary-default-action">default actions</a> of that <a class="def"
href="#glossary-activation-trigger">activation trigger</a>. The value of the <code class="attribute-name"><a href="#widl-Event-target">Event.target</a></code>
MUST be set to the <a class="def" href="#glossary-event-target">event target</a> (normally, the currently focused element), and the event MUST simulate a <em>left
click</em> (i.e., the <a href="#widl-MouseEvent-button"><code>MouseEvent.button</code></a> attribute value MUST be <code>0</code>, and the <a href="#widl-MouseEvent-buttons">
<code>MouseEvent.buttons</code></a> attribute value MUST be <code>1</code>). Other context information of such a simulated <a class="eventtype" href="#event-type-click">
<code>click</code></a> event is implementation dependent, but for historical purposes, the interface for the <a class="eventtype" href="#event-type-click"><code>click</code></a>
event MUST be the <a href="#interface-MouseEvent"><code>MouseEvent interface</code></a>, regardless of the actual device used to activate the element. Preventing
the <a class="def" href="#glossary-default-action">default action</a> of the <a class="def" href="#glossary-activation-trigger">activation trigger</a>, such as
with the <a href="#widl-Event-preventDefault"><code>Event.preventDefault()</code></a>, MUST stop the initiation of the <a class="def" href="#glossary-activation-behavior">
activation behavior</a>.</p>
<div class="example">
<div class="example-title"></div>
<p>When a user activates a hyperlink using a keyboard, such as by focusing the hyperlink element
and pressing the <code class="key">'Enter'</code> or <code class="key">' '</code> key, a <a class="eventtype"
href="#event-type-click"><code>click</code></a> event would be dispatched as the <a class="def" href="#glossary-default-action">default action</a> of the respective
<a class="eventtype" href="#event-type-keydown"><code>keydown</code></a> event.</p>
</div>
<p>Implementations MUST dispatch the synthesized <a class="eventtype" href="#event-type-click"><code>click</code></a> event as described above even if they do not
normally dispatch such an event (e.g., when activation is requested by a voice command, since this specification does not address <a class="def" href="#glossary-event-type">
event types</a> for voice input).</p>
<p class="note"><strong>Note:</strong> 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.</p>
</section> <!-- click-synthesis -->
<section id="events-activation-event-order">
<h3>Activation event order</h3>
<p>Activation triggers and behavior can be defined in part by the events which are dispatched in a set order relative to one another. The following is the typical
sequence of events for an element activated by a pointing device (with only pertinent events listed):</p>
<table class="event-sequence-table">
<tr>
<td class="cell-number"></td>
<th>Event Name</th>
<th>Notes</th>
</tr>
<tr>
<td class="cell-number">1.</td>
<td><a class="eventtype" href="#event-type-click"><code>click</code></a></td>
<td></td>
</tr>
<tr>
<td class="cell-number"></td>
<td></td>
<td>
<em>All <a class="def" href="#glossary-default-action">default actions</a>,
including the <a class="def" href="#glossary-activation-behavior">activation behavior</a></em>
</td>
</tr>
</table>
<p>The following is the typical sequence of events when a focused element is activated by a key event (with only pertinent events listed):</p>
<table class="event-sequence-table">
<tr>
<td class="cell-number"></td>
<th>Event Name</th>
<th>Notes</th>
</tr>
<tr>
<td class="cell-number">1.</td>
<td><a class="eventtype" href="#event-type-keydown"><code>keydown</code></a></td>
<td>MUST be a key which can activate the element, such as the
<code class="key">'Enter'</code> or <code class="key">' '</code> key,
or the element is not activated</td>
</tr>
<tr>
<td class="cell-number">2.</td>
<td><a class="eventtype" href="#event-type-click"><code>click</code></a></td>
<td><a class="def" href="#glossary-default-action">default action</a>; synthesized; <code>isTrusted="true"</code></td>
</tr>
<tr>
<td class="cell-number"></td>
<td></td>
<td>
<em>All <a class="def" href="#glossary-default-action">default actions</a>,
including the <a class="def" href="#glossary-activation-behavior">activation behavior</a></em>
</td>
</tr>
</table>
</section> <!-- events-activation-event-order -->
</section> <!-- event-flow-activation -->
<section id="event-exceptions">
<h2>Event exceptions</h2>
<p><em>This section is informative.</em></p>
<p>Event operations can throw a <code>DOMException</code> as specified in their method descriptions.</p>
<p class="note" id="note-eventexcpetion-removed"><strong>Note:</strong> The exception <em>EventException</em> introduced in <strong class="version">DOM Level 2</strong> is
removed in this specification as part of this specification's normative support of <a href="#references-WebIDL">Web IDL</a>. <em>EventException</em> formerly defined
an exception code <code>UNSPECIFIED_EVENT_TYPE_ERR</code> which is replaced in this specification by the use of a <code>DOMException</code> of type
<code>InvalidStateError</code>.</p>
<p>The following <code>DOMException</code> types are used in this specification.</p>
<table class="exceptiontable">
<tr>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td><code>InvalidStateError</code></td>
<td>Thrown when the <a href="#widl-Event-type"><code>Event.type</code></a> was not specified by initializing the event before <code>dispatchEvent</code> was
called. Also thrown when the <a href="#interface-Event"><code>Event</code></a> object provided to <code>dispatchEvent</code> is already being dispatched.</td>
</tr>
<tr>
<td><code>NotSupportedError</code></td>
<td>Thrown when <a href="#widl-DocumentEvent-createEvent"><code>DocumentEvent.createEvent()</code></a> is passed an <a href="#interface-Event"><code>Event</code></a>
interface that the implementation does not support.</td>
</tr>
</table>
</section> <!-- event-exceptions -->
<section id="event-constructors">
<h2>Constructing Mouse and Keyboard Events</h2>
<p>Generally, when a constructor of an <a href="#interface-Event"><code>Event</code></a> interface,
or of an interface inherited from the <a href="#interface-Event"><code>Event</code></a> interface,
is invoked, the steps described in DOM4 [<a href="#references-DOM4">DOM4</a>] should be followed.
However the <a href="#interface-KeyboardEvent"><code>KeyboardEvent</code></a> and
<a href="#interface-MouseEvent"><code>MouseEvent</code></a> interfaces provide additional
dictionary members for initializing the internal state of the
<a href="#interface-Event"><code>Event</code></a> object's key modifiers: specifically, the
internal state queried for using the
<a href="#widl-KeyboardEvent-getModifierState"><code>KeyboardEvent.getModifierState()</code></a>
and <a href="#widl-MouseEvent-getModifierState"><code>MouseEvent.getModifierState()</code></a>
methods. This section supplements the DOM4 steps for intializing a new
<a href="#interface-Event"><code>Event</code></a> object with these optional modifier states.
</p>
<p>For the purposes of constructing a <a href="#interface-KeyboardEvent"><code>KeyboardEvent</code></a>,
<a href="#interface-MouseEvent"><code>MouseEvent</code></a>, or object derived from these objects
using the algorithm below, all
<a href="#interface-KeyboardEvent"><code>KeyboardEvent</code></a>,
<a href="#interface-MouseEvent"><code>MouseEvent</code></a>, and derived objects have
<dfn id="internal-key-modifier-state">internal key modifier state</dfn> which can be set and
retreived using the <a href="#keys-modifiers">key modifier names</a>:
<code class="key">'AltGraph'</code>
<code class="key">'CapsLock'</code>
<code class="key">'Fn'</code>
<code class="key">'FnLock'</code>
<code class="key">'Hyper'</code>
<code class="key">'NumLock'</code>
<code class="key">'ScrollLock'</code>
<code class="key">'Super'</code>
<code class="key">'Symbol'</code> and
<code class="key">'SymbolLock'</code>.
<p>The following steps supplement the algorithm defined for constructing events in DOM4:</p>
<ol>
<li>If the <a href="#interface-Event"><code>Event</code></a> being constructed is a
<a href="#interface-KeyboardEvent"><code>KeyboardEvent</code></a> or
<a href="#interface-MouseEvent"><code>MouseEvent</code></a> object or an object that
derives from either of these, and a
<a href="#event-modifier-initializers">EventModifierInit</a>
argument was provided to the constructor, then run the following sub-steps:
<ol>
<li>For each <a href="#event-modifier-initializers">EventModifierInit</a>
argument, if the dictionary member begins with the string <code>"modifier"</code>, then
let the <dfn id="modifier-key-name">key modifier name</dfn> be the dictionary member's name
excluding the prefix <code>"modifier"</code>, and set the
<a href="#interface-Event"><code>Event</code></a> object's
<a href="#internal-key-modifier-state">internal key modifier state</a> that
matches the <a href="#modifier-key-name">key modifier name</a> to the corresponding value.
</ol>
</ol>
</section>
</section> <!-- dom-event-architecture -->
<!-- Section 4: Basic Event Interfaces ========================================================-->
<section id="event-interfaces">
<h1>Basic Event Interfaces</h1>
<p>The basic event interfaces defined in DOM4
[<a href="#references-DOM4">DOM4</a>] are fundamental to UI Events.
These basic event interfaces MUST always be supported by the implementation:
</p>
<ul>
<li>The <code id="interface-Event">Event</code> interface and its following constants, methods and attributes:
<ul>
<li><code id="widl-Event-NONE">NONE</code> constant</li>
<li><code id="widl-Event-CAPTURING_PHASE">CAPTURING_PHASE</code> constant</li>
<li><code id="widl-Event-AT_TARGET">AT_TARGET</code> constant</li>
<li><code id="widl-Event-BUBBLING_PHASE">BUBBLING_PHASE</code> constant</li>
<li><code id="widl-Event-type">type</code> attribute</li>
<li><code id="widl-Event-target">target</code> attribute</li>
<li><code id="widl-Event-currentTarget">currentTarget</code> attribute</li>
<li><code id="widl-Event-eventPhase">eventPhase</code> attribute</li>
<li><code id="widl-Event-bubbles">bubbles</code> attribute</li>
<li><code id="widl-Event-cancelable">cancelable</code> attribute</li>
<li><code id="widl-Event-timeStamp">timeStamp</code> attribute</li>
<li><code id="widl-Event-defaultPrevented">defaultPrevented</code> attribute</li>
<li><code id="widl-Event-isTrusted">isTrusted</code> attribute</li>
<li><code id="widl-Event-stopPropagation">stopPropagation()</code> method</li>
<li><code id="widl-Event-stopImmediatePropagation">stopImmediatePropagation()</code> method</li>
<li><code id="widl-Event-preventDefault">preventDefault()</code> method</li>
<li><code id="widl-Event-initEvent">initEvent()</code> method</li>
</ul>
</li>
<li>The <code id="interface-CustomEvent">CustomEvent</code> interface and its following method and attribute:
<ul>
<li><code id="widl-CustomEvent-initCustomEvent">initCustomEvent()</code> method</li>
<li><code id="widl-CustomEvent-detail">detail</code> attribute</li>
</ul>
</li>
<li>The <code id="interface-EventTarget">EventTarget</code> interface and its following methods:
<ul>
<li><code id="widl-EventTarget-addEventListener">addEventListener()</code> method</li>
<li><code id="widl-EventTarget-removeEventListener">removeEventListener()</code> method</li>
<li><code id="widl-EventTarget-dispatchEvent">dispatchEvent()</code> method</li>
</ul>
</li>
<li>The <code id="interface-EventListener">EventListener</code> interface and its <code id="widl-EventListener-handleEvent">handleEvent</code> method</li>
<li>The <code>Document</code> interface's <code id="widl-DocumentEvent-createEvent">createEvent</code> method</li>
</ul>
<p>The event types defined in this specification derive from these basic interfaces, and MUST
inherit all of the attributes, methods, and constants of the interfaces they derive from.
</p>
<p>The following chart describes the inheritance structure of the interfaces described in this specification.
</p>
<figure id="figure-event-inheritance">
<img src='images/event-inheritance.svg' height="180" alt="Graphical representation of inheritance of interfaces defined by this specification" />
<figcaption>Graphical representation of inheritance of interfaces defined by this specification</figcaption>
</figure>
<section id="event-types-list">
<h3>List of Event Types</h3>
<p>Each event MUST be associated with a type, called <em>event type</em> and available as the <a href="#widl-Event-type"><code class="interface-attribute">type</code></a>
attribute on the event object. The event type MUST be of type <code>DOMString</code>.</p>
<p>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 [<cite><a class="informative" href="#references-XML">XML 1.0</a></cite>] or
[<cite><a class="informative" href="#references-HTML5">HTML5</a></cite>] application, the specifications of those languages MAY restrict the
semantics and scope (in particular the possible <a class="def" href="#glossary-event-target">event targets</a>) 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.</p>
<p>The following table provides an informative summary of the event types described in this specification.</p>
<table class="data-table">
<tr>
<th>Event Type</th>
<th>Sync / Async</th>
<th>Bubbling phase</th>
<th>Trusted event target types</th>
<th>DOM interface</th>
<th>Cancelable</th>
<th>Default Action</th>
</tr>
<tr>
<td><a class="eventtype" href="#event-type-abort"><code>abort</code></a></td>
<td>Sync</td>
<td>No</td>
<td><a class="def" href="#glossary-window"><code>Window</code></a>, <code>Element</code></td>
<td><a href="#interface-Event"><code>Event</code></a></td>
<td>No</td>
<td>None</td>
</tr>
<tr>
<td><a class="eventtype" href="#event-type-beforeinput"><code>beforeinput</code></a></td>
<td>Sync</td>
<td>Yes</td>
<td><code>Element</code></td>
<td><a href="#interface-InputEvent"><code>InputEvent</code></a></td>
<td>Yes</td>
<td>Update the DOM element</td>
</tr>
<tr>
<td><a class="eventtype" href="#event-type-blur"><code>blur</code></a></td>
<td>Sync</td>
<td>No</td>
<td><a class="def" href="#glossary-window"><code>Window</code></a>, <code>Element</code></td>
<td><a href="#interface-FocusEvent"><code>FocusEvent</code></a></td>
<td>No</td>
<td>None</td>
</tr>
<tr>
<td><a class="eventtype" href="#event-type-click"><code>click</code></a></td>
<td>Sync</td>
<td>Yes</td>
<td><code>Element</code></td>
<td><a href="#interface-MouseEvent"><code>MouseEvent</code></a></td>
<td>Yes</td>
<td>Varies:
for <a class="def" href="#glossary-event-target">targets</a> with an associated activation
behavior, executes the <a class="def" href="#glossary-activation-behavior">activation behavior</a>;
for focusable <a class="def" href="#glossary-event-target">targets</a>, gives the element focus.
</td>
</tr>
<tr>
<td><a class="eventtype" href="#event-type-compositionstart"><code>compositionstart</code></a></td>
<td>Sync</td>
<td>Yes</td>
<td><code>Element</code></td>
<td><a href="#interface-CompositionEvent"><code>CompositionEvent</code></a></td>
<td>Yes</td>
<td>Show a <a class="def" href="#glossary-text-composition-system">text composition system</a> candidate window</td>
</tr>
<tr>
<td><a class="eventtype" href="#event-type-compositionupdate"><code>compositionupdate</code></a></td>
<td>Sync</td>
<td>Yes</td>
<td><code>Element</code></td>
<td><a href="#interface-CompositionEvent"><code>CompositionEvent</code></a></td>
<td>No</td>
<td>None</td>
</tr>
<tr>
<td><a class="eventtype" href="#event-type-compositionend"><code>compositionend</code></a></td>
<td>Sync</td>
<td>Yes</td>
<td><code>Element</code></td>
<td><a href="#interface-CompositionEvent"><code>CompositionEvent</code></a></td>
<td>No</td>
<td>None</td>
</tr>
<tr>
<td><a class="eventtype" href="#event-type-dblclick"><code>dblclick</code></a></td>
<td>Sync</td>
<td>Yes</td>
<td><code>Element</code></td>
<td><a href="#interface-MouseEvent"><code>MouseEvent</code></a></td>
<td>No</td>
<td>Varies:
for <a class="def" href="#glossary-event-target">targets</a> with an associated activation
behavior, executes the <a class="def" href="#glossary-activation-behavior">activation behavior</a>;
for focusable <a class="def" href="#glossary-event-target">targets</a>, gives the element focus;
for selectable <a class="def" href="#glossary-event-target">targets</a>, selects part or all of the
element's content.
</td>
</tr>
<tr>
<td><a class="eventtype" href="#event-type-error"><code>error</code></a></td>
<td>Async</td>
<td>No</td>
<td><a class="def" href="#glossary-window"><code>Window</code></a>, <code>Element</code></td>
<td><a href="#interface-Event"><code>Event</code></a></td>
<td>No</td>
<td>None</td>
</tr>
<tr>
<td><a class="eventtype" href="#event-type-focus"><code>focus</code></a></td>
<td>Sync</td>
<td>No</td>
<td><a class="def" href="#glossary-window"><code>Window</code></a>, <code>Element</code></td>
<td><a href="#interface-FocusEvent"><code>FocusEvent</code></a></td>
<td>No</td>
<td>None</td>
</tr>