forked from w3c/uievents
-
Notifications
You must be signed in to change notification settings - Fork 0
/
TR.html
10645 lines (9688 loc) · 744 KB
/
TR.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>
<html data-bug-component="DOM3 Events" data-bug-product="WebAppsWG" typeof="bibo:Document w3p:WD" prefix="bibo: http://purl.org/ontology/bibo/ w3p: http://www.w3.org/2001/02pd/rec54#" lang="en-US"><head><meta property="dc:language" content="en" lang="">
<meta charset="UTF-8">
<title>UI Events (formerly DOM Level 3 Events)</title>
<style>/* --- ISSUES/NOTES --- */
div.issue-title, div.note-title , div.warning-title {
padding-right: 1em;
min-width: 7.5em;
color: #b9ab2d;
}
div.issue-title { color: #e05252; }
div.note-title { color: #2b2; }
div.warning-title { color: #f22; }
div.issue-title span, div.note-title span, div.warning-title span {
text-transform: uppercase;
}
div.note, div.issue, div.warning {
margin-top: 1em;
margin-bottom: 1em;
}
.note > p:first-child, .issue > p:first-child, .warning > p:first-child { margin-top: 0 }
.issue, .note, .warning {
padding: .5em;
border-left-width: .5em;
border-left-style: solid;
}
div.issue, div.note , div.warning {
padding: 1em 1.2em 0.5em;
margin: 1em 0;
position: relative;
clear: both;
}
span.note, span.issue, span.warning { padding: .1em .5em .15em; }
.issue {
border-color: #e05252;
background: #fbe9e9;
}
.note {
border-color: #52e052;
background: #e9fbe9;
}
.warning {
border-color: #f11;
border-right-width: .2em;
border-top-width: .2em;
border-bottom-width: .2em;
border-style: solid;
background: #fbe9e9;
}
.warning-title:before{
content: "⚠"; /*U+26A0 WARNING SIGN*/
font-size: 3em;
float: left;
height: 100%;
padding-right: .3em;
vertical-align: top;
margin-top: -0.5em;
}
</style><style>/* --- WEB IDL --- */
pre.idl {
border-top: 1px solid #90b8de;
border-bottom: 1px solid #90b8de;
padding: 1em;
line-height: 120%;
}
pre.idl::before {
content: "WebIDL";
display: block;
width: 150px;
background: #90b8de;
color: #fff;
font-family: initial;
padding: 3px;
font-weight: bold;
margin: -1em 0 1em -1em;
}
.idlType {
color: #ff4500;
font-weight: bold;
text-decoration: none;
}
/*.idlModule*/
/*.idlModuleID*/
/*.idlInterface*/
.idlInterfaceID, .idlDictionaryID, .idlCallbackID, .idlEnumID {
font-weight: bold;
color: #005a9c;
}
a.idlEnumItem {
color: #000;
border-bottom: 1px dotted #ccc;
text-decoration: none;
}
.idlSuperclass {
font-style: italic;
color: #005a9c;
}
/*.idlAttribute*/
.idlAttrType, .idlFieldType, .idlMemberType {
color: #005a9c;
}
.idlAttrName, .idlFieldName, .idlMemberName {
color: #ff4500;
}
.idlAttrName a, .idlFieldName a, .idlMemberName a {
color: #ff4500;
border-bottom: 1px dotted #ff4500;
text-decoration: none;
}
/*.idlMethod*/
.idlMethType, .idlCallbackType {
color: #005a9c;
}
.idlMethName {
color: #ff4500;
}
.idlMethName a {
color: #ff4500;
border-bottom: 1px dotted #ff4500;
text-decoration: none;
}
/*.idlCtor*/
.idlCtorName {
color: #ff4500;
}
.idlCtorName a {
color: #ff4500;
border-bottom: 1px dotted #ff4500;
text-decoration: none;
}
/*.idlParam*/
.idlParamType {
color: #005a9c;
}
.idlParamName, .idlDefaultValue {
font-style: italic;
}
.extAttr {
color: #666;
}
/*.idlSectionComment*/
.idlSectionComment {
color: gray;
}
/*.idlMaplike*/
.idlMaplikeKeyType, .idlMaplikeValueType {
color: #005a9c;
}
/*.idlConst*/
.idlConstType {
color: #005a9c;
}
.idlConstName {
color: #ff4500;
}
.idlConstName a {
color: #ff4500;
border-bottom: 1px dotted #ff4500;
text-decoration: none;
}
/*.idlException*/
.idlExceptionID {
font-weight: bold;
color: #c00;
}
.idlTypedefID, .idlTypedefType {
color: #005a9c;
}
.idlRaises, .idlRaises a.idlType, .idlRaises a.idlType code, .excName a, .excName a code {
color: #c00;
font-weight: normal;
}
.excName a {
font-family: monospace;
}
.idlRaises a.idlType, .excName a.idlType {
border-bottom: 1px dotted #c00;
}
.excGetSetTrue, .excGetSetFalse, .prmNullTrue, .prmNullFalse, .prmOptTrue, .prmOptFalse {
width: 45px;
text-align: center;
}
.excGetSetTrue, .prmNullTrue, .prmOptTrue { color: #0c0; }
.excGetSetFalse, .prmNullFalse, .prmOptFalse { color: #c00; }
.idlImplements a {
font-weight: bold;
}
dl.attributes, dl.methods, dl.constants, dl.constructors, dl.fields, dl.dictionary-members {
margin-left: 2em;
}
.attributes dt, .methods dt, .constants dt, .constructors dt, .fields dt, .dictionary-members dt {
font-weight: normal;
}
.attributes dt code, .methods dt code, .constants dt code, .constructors dt code, .fields dt code, .dictionary-members dt code {
font-weight: bold;
color: #000;
font-family: monospace;
}
.attributes dt code, .fields dt code, .dictionary-members dt code {
background: #ffffd2;
}
.attributes dt .idlAttrType code, .fields dt .idlFieldType code, .dictionary-members dt .idlMemberType code {
color: #005a9c;
background: transparent;
font-family: inherit;
font-weight: normal;
font-style: italic;
}
.methods dt code {
background: #d9e6f8;
}
.constants dt code {
background: #ddffd2;
}
.constructors dt code {
background: #cfc;
}
.attributes dd, .methods dd, .constants dd, .constructors dd, .fields dd, .dictionary-members dd {
margin-bottom: 1em;
}
table.parameters, table.exceptions {
border-spacing: 0;
border-collapse: collapse;
margin: 0.5em 0;
width: 100%;
}
table.parameters { border-bottom: 1px solid #90b8de; }
table.exceptions { border-bottom: 1px solid #deb890; }
.parameters th, .exceptions th {
color: #fff;
padding: 3px 5px;
text-align: left;
font-family: initial;
font-weight: normal;
text-shadow: #666 1px 1px 0;
}
.parameters th { background: #90b8de; }
.exceptions th { background: #deb890; }
.parameters td, .exceptions td {
padding: 3px 10px;
border-top: 1px solid #ddd;
vertical-align: top;
}
.parameters tr:first-child td, .exceptions tr:first-child td {
border-top: none;
}
.parameters td.prmName, .exceptions td.excName, .exceptions td.excCodeName {
width: 100px;
}
.parameters td.prmType {
width: 120px;
}
table.exceptions table {
border-spacing: 0;
border-collapse: collapse;
width: 100%;
}
</style><link rel="author" href="mailto:[email protected]">
<link rel="help" href="http://www.w3.org/DOM/">
<link rel="stylesheet" type="text/css" href="override.css">
<link rel="stylesheet" type="text/css" href="w3c-tr.css">
<style>/*****************************************************************
* ReSpec 3 CSS
* Robin Berjon - http://berjon.com/
*****************************************************************/
/* --- INLINES --- */
em.rfc2119 {
text-transform: lowercase;
font-variant: small-caps;
font-style: normal;
color: #900;
}
h1 acronym, h2 acronym, h3 acronym, h4 acronym, h5 acronym, h6 acronym, a acronym,
h1 abbr, h2 abbr, h3 abbr, h4 abbr, h5 abbr, h6 abbr, a abbr {
border: none;
}
dfn {
font-weight: bold;
}
a.internalDFN {
color: inherit;
border-bottom: 1px solid #99c;
text-decoration: none;
}
a.externalDFN {
color: inherit;
border-bottom: 1px dotted #ccc;
text-decoration: none;
}
a.bibref {
text-decoration: none;
}
cite .bibref {
font-style: normal;
}
code {
color: #C83500;
}
/* --- TOC --- */
.toc a, .tof a {
text-decoration: none;
}
a .secno, a .figno {
color: #000;
}
ul.tof, ol.tof {
list-style: none outside none;
}
.caption {
margin-top: 0.5em;
font-style: italic;
}
/* --- TABLE --- */
table.simple {
border-spacing: 0;
border-collapse: collapse;
border-bottom: 3px solid #005a9c;
}
.simple th {
background: #005a9c;
color: #fff;
padding: 3px 5px;
text-align: left;
}
.simple th[scope="row"] {
background: inherit;
color: inherit;
border-top: 1px solid #ddd;
}
.simple td {
padding: 3px 10px;
border-top: 1px solid #ddd;
}
.simple tr:nth-child(even) {
background: #f0f6ff;
}
/* --- DL --- */
.section dd > p:first-child {
margin-top: 0;
}
.section dd > p:last-child {
margin-bottom: 0;
}
.section dd {
margin-bottom: 1em;
}
.section dl.attrs dd, .section dl.eldef dd {
margin-bottom: 0;
}
@media print {
.removeOnSave {
display: none;
}
}
</style><link href="https://www.w3.org/StyleSheets/TR/W3C-WD" rel="stylesheet"><!--[if lt IE 9]><script src='https://www.w3.org/2008/site/js/html5shiv.js'></script><![endif]--></head>
<body id="respecDocument" role="document" class="h-entry"><div id="respecHeader" role="contentinfo" class="head">
<p>
<a href="https://www.w3.org/"><img src="https://www.w3.org/Icons/w3c_home" alt="W3C" height="48" width="72"></a>
</p>
<h1 class="title p-name" id="title" property="dcterms:title">UI Events (formerly DOM Level 3 Events)</h1>
<h2 id="w3c-working-draft-28-april-2015"><abbr title="World Wide Web Consortium">W3C</abbr> Working Draft <time property="dcterms:issued" class="dt-published" datetime="2015-04-28">28 April 2015</time></h2>
<dl>
<dt>This version:</dt>
<dd><a class="u-url" href="http://www.w3.org/TR/2015/WD-uievents-20150428/">http://www.w3.org/TR/2015/WD-uievents-20150428/</a></dd>
<dt>Latest published version:</dt>
<dd><a href="http://www.w3.org/TR/uievents/">http://www.w3.org/TR/uievents/</a></dd>
<dt>Latest editor's draft:</dt>
<dd><a href="https://w3c.github.io/uievents/">https://w3c.github.io/uievents/</a></dd>
<dt>Previous version:</dt>
<dd><a rel="dcterms:replaces" href="http://www.w3.org/TR/2015/WD-uievents-20150319/">http://www.w3.org/TR/2015/WD-uievents-20150319/</a></dd>
<dt>Editors:</dt>
<dd class="p-author h-card vcard" property="bibo:editor" resource="_:editor0"><span property="rdf:first" typeof="foaf:Person"><meta property="foaf:name" content="Gary Kacmarcik"><a class="u-url url p-name fn" property="foaf:homepage" href="mailto:[email protected]?subject=%5BUI-events%5D%20Spec%20Feedback">Gary Kacmarcik</a>, <a property="foaf:workplaceHomepage" class="p-org org h-org h-card" href="http://www.google.com">Google, Inc.</a> (since Jun 2013)</span>
<span property="rdf:rest" resource="_:editor1"></span>
</dd>
<dd class="p-author h-card vcard" resource="_:editor1"><span property="rdf:first" typeof="foaf:Person"><meta property="foaf:name" content="Travis Leithead"><a class="u-url url p-name fn" property="foaf:homepage" href="mailto:[email protected]?subject=%5BUI-events%5D%20Spec%20Feedback">Travis Leithead</a>, <a property="foaf:workplaceHomepage" class="p-org org h-org h-card" href="http://www.microsoft.com">Microsoft Corp.</a> (since Feb 2012)</span>
<span property="rdf:rest" resource="rdf:nil"></span>
</dd>
<dt>Participate:</dt>
<dd>
<a href="https://www.w3.org/Bugs/Public/enter_bug.cgi?component=DOM3%20Events&product=WebAppsWG">
File a bug
</a>
</dd>
<dd>
<a href="https://www.w3.org/Bugs/Public/buglist.cgi?component=UI%20Events&list_id=55051&product=WebAppsWG&resolution=---">
Bug list
</a>
</dd>
<dd>
<a href="http://lists.w3.org/Archives/Public/www-dom/">
Mailing list archive (www-dom)
</a>
</dd>
<dd>
<a href="https://github.com/w3c/uievents">
Github repository
</a>
</dd>
<dd>
<a href="https://github.com/w3c/uievents/commits">
Commit history
</a>
</dd>
<dd>
<a href="http://www.w3.org/2008/webapps/wiki/DOM3Events">
UI Events Wiki Home
</a>
</dd>
</dl>
<p class="copyright">
<a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> ©
2015
<a href="http://www.w3.org/"><abbr title="World Wide Web Consortium">W3C</abbr></a><sup>®</sup>
(<a href="http://www.csail.mit.edu/"><abbr title="Massachusetts Institute of Technology">MIT</abbr></a>,
<a href="http://www.ercim.eu/"><abbr title="European Research Consortium for Informatics and Mathematics">ERCIM</abbr></a>,
<a href="http://www.keio.ac.jp/">Keio</a>, <a href="http://ev.buaa.edu.cn/">Beihang</a>).
<abbr title="World Wide Web Consortium">W3C</abbr> <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>,
<a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and
<a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a>
rules apply.
</p>
<hr>
</div>
<!-- Section: Abstract ========================================================-->
<section property="dc:abstract" class="introductory" id="abstract"><h2 resource="#h-abstract" id="h-abstract"><span property="xhv:role" resource="xhv:heading">Abstract</span></h2>
<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><section id="sotd" class="introductory"><h2 resource="#h-sotd" id="h-sotd"><span property="xhv:role" resource="xhv:heading">Status of This Document</span></h2>
<p>
<em>This section describes the status of this document at the time of its publication.
Other documents may supersede this document. A list of current <abbr title="World Wide Web Consortium">W3C</abbr> publications and the
latest revision of this technical report can be found in the <a href="http://www.w3.org/TR/"><abbr title="World Wide Web Consortium">W3C</abbr> technical reports index</a> at
http://www.w3.org/TR/.</em>
</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>
<p>
<strong class="redNote">The previous version of the <a href='http://www.w3.org/TR/2014/WD-uievents-20140612/'>UI Events specification</a> was extending DOM Level 3 Events but has been abandoned for now, due to the lack of time to work out the details of '<code><a href="http://www.w3.org/TR/2014/WD-uievents-20140612/#widl-KeyboardEvent-locale">locale</a></code>'</strong>. Future extensions may also be subsumed by additional work and proposals around the <a href="https://docs.google.com/document/d/1WLadG2dn4vlCewOmUtUEoRsThiptC7Ox28CRmYUn8Uw/edit">InputDevice API</a>, allowing access to information related to the physical device responsible for an event.
</p>
<p>
This document was published by the <a href="http://www.w3.org/2008/webapps/">Web Applications Working Group</a> as a Working Draft.
This document is intended to become a <abbr title="World Wide Web Consortium">W3C</abbr> Recommendation.
If you wish to make comments regarding this document, please send them to
<a href="mailto:[email protected]">[email protected]</a>
(<a href="mailto:[email protected]?subject=subscribe">subscribe</a>,
<a href="http://lists.w3.org/Archives/Public/www-dom/">archives</a>).
All comments are welcome.
</p>
<p>
Publication as a Working Draft does not imply endorsement by the <abbr title="World Wide Web Consortium">W3C</abbr>
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 was produced by a group operating under the
<a id="sotd_patent" property="w3p:patentRules" href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February 2004 <abbr title="World Wide Web Consortium">W3C</abbr> Patent
Policy</a>.
<abbr title="World Wide Web Consortium">W3C</abbr> maintains a <a href="http://www.w3.org/2004/01/pp-impl/42538/status" rel="disclosure">public list of any patent
disclosures</a>
made in connection with the deliverables of the group; that page also includes
instructions for disclosing a patent. An individual who has actual knowledge of a patent
which the individual believes contains
<a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
Claim(s)</a> must disclose the information in accordance with
<a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
6 of the <abbr title="World Wide Web Consortium">W3C</abbr> Patent Policy</a>.
</p>
<p>This document is governed by the <a id="w3c_process_revision" href="http://www.w3.org/2014/Process-20140801/">1 August 2014 <abbr title="World Wide Web Consortium">W3C</abbr> Process Document</a>.
</p>
</section><section id="toc"><h2 resource="#h-toc" id="h-toc" class="introductory"><span property="xhv:role" resource="xhv:heading">Table of Contents</span></h2><ul id="respecContents" role="directory" class="toc"><li class="tocline"><a class="tocxref" href="#dom-events-intro"><span class="secno">1. </span>Introduction</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#dom-events-overview"><span class="secno">1.1 </span>Overview</a></li><li class="tocline"><a class="tocxref" href="#dom-events-conformance"><span class="secno">1.2 </span>Conformance</a></li><li class="tocline"><a class="tocxref" href="#style-conventions"><span class="secno">1.3 </span>Stylistic Conventions</a></li></ul></li><li class="tocline"><a class="tocxref" href="#issues"><span class="secno">2. </span>Issues</a></li><li class="tocline"><a class="tocxref" href="#dom-event-architecture"><span class="secno">3. </span>DOM Event Architecture</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#event-flow"><span class="secno">3.1 </span>Event dispatch and DOM event flow</a></li><li class="tocline"><a class="tocxref" href="#event-flow-default-cancel"><span class="secno">3.2 </span>Default actions and cancelable events</a></li><li class="tocline"><a class="tocxref" href="#sync-async"><span class="secno">3.3 </span>Synchronous and asynchronous events</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#event-order-and-loops"><span class="secno">3.3.1 </span>Event order and event loops</a></li></ul></li><li class="tocline"><a class="tocxref" href="#trusted-events"><span class="secno">3.4 </span>Trusted events</a></li><li class="tocline"><a class="tocxref" href="#event-flow-activation"><span class="secno">3.5 </span>Activation triggers and behavior</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#click-synthesis"><span class="secno">3.5.1 </span>Activation event synthesis</a></li><li class="tocline"><a class="tocxref" href="#events-activation-event-order"><span class="secno">3.5.2 </span>Activation event order</a></li></ul></li><li class="tocline"><a class="tocxref" href="#event-exceptions"><span class="secno">3.6 </span>Event exceptions</a></li><li class="tocline"><a class="tocxref" href="#event-constructors"><span class="secno">3.7 </span>Constructing Mouse and Keyboard Events</a></li></ul></li><li class="tocline"><a class="tocxref" href="#event-interfaces"><span class="secno">4. </span>Basic Event Interfaces</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#event-types-list"><span class="secno">4.1 </span>List of Event Types</a></li></ul></li><li class="tocline"><a class="tocxref" href="#event-types"><span class="secno">5. </span>Event Types</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#events-uievents"><span class="secno">5.1 </span>User Interface Event Types</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#interface-UIEvent"><span class="secno">5.1.1 </span>Interface UIEvent</a><ul class="toc"></ul></li></ul></li><li class="tocline"><a class="tocxref" href="#events-focusevent"><span class="secno">5.2 </span>Focus Event Types</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#interface-FocusEvent"><span class="secno">5.2.1 </span>Interface FocusEvent</a><ul class="toc"></ul></li><li class="tocline"><a class="tocxref" href="#events-focusevent-event-order"><span class="secno">5.2.2 </span>Focus Event Order</a></li><li class="tocline"><a class="tocxref" href="#events-focusevent-doc-focus"><span class="secno">5.2.3 </span>Document Focus and Focus Context</a></li></ul></li><li class="tocline"><a class="tocxref" href="#events-mouseevents"><span class="secno">5.3 </span>Mouse Event Types</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#interface-MouseEvent"><span class="secno">5.3.1 </span>Interface MouseEvent</a><ul class="toc"></ul></li><li class="tocline"><a class="tocxref" href="#event-modifier-initializers"><span class="secno">5.3.2 </span>Event Modifier Initializers</a><ul class="toc"></ul></li><li class="tocline"><a class="tocxref" href="#events-mouseevent-event-order"><span class="secno">5.3.3 </span>Mouse Event Order</a></li></ul></li><li class="tocline"><a class="tocxref" href="#events-wheelevents"><span class="secno">5.4 </span>Wheel Event Types</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#interface-WheelEvent"><span class="secno">5.4.1 </span>Interface WheelEvent</a><ul class="toc"></ul></li></ul></li><li class="tocline"><a class="tocxref" href="#events-keyboardevents"><span class="secno">5.5 </span>Keyboard Event Types</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#interface-KeyboardEvent"><span class="secno">5.5.1 </span>Interface KeyboardEvent</a><ul class="toc"></ul></li><li class="tocline"><a class="tocxref" href="#events-keyboard-event-order"><span class="secno">5.5.2 </span>Keyboard Event Order</a></li></ul></li><li class="tocline"><a class="tocxref" href="#events-compositionevents"><span class="secno">5.6 </span>Composition Event Types</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#interface-CompositionEvent"><span class="secno">5.6.1 </span>Interface CompositionEvent</a><ul class="toc"></ul></li><li class="tocline"><a class="tocxref" href="#events-composition-event-order"><span class="secno">5.6.2 </span>Composition Event Order</a></li><li class="tocline"><a class="tocxref" href="#handwriting"><span class="secno">5.6.3 </span>Handwriting Recognition Systems</a></li><li class="tocline"><a class="tocxref" href="#events-composition-event-canceling"><span class="secno">5.6.4 </span>Canceling Composition Events</a></li><li class="tocline"><a class="tocxref" href="#events-composition-event-key-events"><span class="secno">5.6.5 </span>Key Events During Composition</a><ul class="toc"></ul></li><li class="tocline"><a class="tocxref" href="#events-composition-event-types"><span class="secno">5.6.6 </span>Composition Event Types</a></li></ul></li></ul></li><li class="tocline"><a class="tocxref" href="#keys"><span class="secno">6. </span>Keyboard events and key values</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#keyboard-input"><span class="secno">6.1 </span>Keyboard Input</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#key-legends"><span class="secno">6.1.1 </span>Key Legends</a></li></ul></li><li class="tocline"><a class="tocxref" href="#keys-codevalues"><span class="secno">6.2 </span>Key codes</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#code-motivation"><span class="secno">6.2.1 </span>Motivation for Adding the <code>code</code> Attribute</a></li><li class="tocline"><a class="tocxref" href="#relationship-between-key-code"><span class="secno">6.2.2 </span>The Relationship Between <code>key</code> and <code>code</code></a></li><li class="tocline"><a class="tocxref" href="#code-examples"><span class="secno">6.2.3 </span><code>code</code> Examples</a></li><li class="tocline"><a class="tocxref" href="#code-virtual-keyboards"><span class="secno">6.2.4 </span><code>code</code> and Virtual Keyboards</a></li></ul></li><li class="tocline"><a class="tocxref" href="#keys-keyvalues"><span class="secno">6.3 </span>Keyboard Event <code>key</code> Values</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#keys-unicode"><span class="secno">6.3.1 </span>Key Values and Unicode</a></li><li class="tocline"><a class="tocxref" href="#keys-modifiers"><span class="secno">6.3.2 </span>Modifier keys</a></li><li class="tocline"><a class="tocxref" href="#keys-dead"><span class="secno">6.3.3 </span>Dead keys</a></li><li class="tocline"><a class="tocxref" href="#keys-IME"><span class="secno">6.3.4 </span>Input Method Editors</a><ul class="toc"></ul></li><li class="tocline"><a class="tocxref" href="#keys-cancelable-keys"><span class="secno">6.3.5 </span>Default actions and cancelable keyboard events</a></li><li class="tocline"><a class="tocxref" href="#keys-guidelines"><span class="secno">6.3.6 </span>Guidelines for selecting key values</a></li></ul></li></ul></li><li class="tocline"><a class="tocxref" href="#legacy-event-initializers"><span class="secno">A. </span>Legacy Event Initializers</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#legacy-event-initializer-interfaces"><span class="secno">A.1 </span>Legacy Event Initializer Interfaces</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#idl-interface-CustomEvent-initializers"><span class="secno">A.1.1 </span>Initializers for interface CustomEvent</a><ul class="toc"></ul></li><li class="tocline"><a class="tocxref" href="#idl-interface-UIEvent-initializers"><span class="secno">A.1.2 </span>Initializers for interface UIEvent</a><ul class="toc"></ul></li><li class="tocline"><a class="tocxref" href="#idl-interface-FocusEvent-initializers"><span class="secno">A.1.3 </span>Initializers for interface FocusEvent</a><ul class="toc"></ul></li><li class="tocline"><a class="tocxref" href="#idl-interface-MouseEvent-initializers"><span class="secno">A.1.4 </span>Initializers for interface MouseEvent</a><ul class="toc"></ul></li><li class="tocline"><a class="tocxref" href="#idl-interface-WheelEvent-initializers"><span class="secno">A.1.5 </span>Initializers for interface WheelEvent</a><ul class="toc"></ul></li><li class="tocline"><a class="tocxref" href="#idl-interface-KeyboardEvent-initializers"><span class="secno">A.1.6 </span>Initializers for interface KeyboardEvent</a><ul class="toc"></ul></li><li class="tocline"><a class="tocxref" href="#idl-interface-CompositionEvent-initializers"><span class="secno">A.1.7 </span>Initializers for interface CompositionEvent</a><ul class="toc"></ul></li></ul></li></ul></li><li class="tocline"><a class="tocxref" href="#legacy-key-attributes"><span class="secno">B. </span>Legacy Key Attributes</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#KeyboardEvent-supplemental-interface"><span class="secno">B.1 </span>Legacy <span class="formerLink"><code>KeyboardEvent</code></span> supplemental interface</a></li><li class="tocline"><a class="tocxref" href="#legacy-key-models"><span class="secno">B.2 </span>Legacy key models</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#determine-keydown-keyup-keyCode"><span class="secno">B.2.1 </span>How to determine <code class="attribute-name">keyCode</code> for <code>keydown</code> and <code>keyup</code> events</a></li><li class="tocline"><a class="tocxref" href="#determine-keypress-keyCode"><span class="secno">B.2.2 </span>How to determine <code class="attribute-name">keyCode</code> for <span class="formerLink"><code>keypress</code></span> events</a></li><li class="tocline"><a class="tocxref" href="#fixed-virtual-key-codes"><span class="secno">B.2.3 </span>Fixed virtual key codes</a></li><li class="tocline"><a class="tocxref" href="#optionally-fixed-virtual-key-codes"><span class="secno">B.2.4 </span>Optionally fixed virtual key codes</a></li></ul></li></ul></li><li class="tocline"><a class="tocxref" href="#legacy-event-types"><span class="secno">C. </span>Legacy Event Types</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#legacy-uievent-events"><span class="secno">C.1 </span>Legacy <span class="formerLink"><code>UIEvent</code></span> events</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#legacy-uievent-event-order"><span class="secno">C.1.1 </span>Activation event order</a></li></ul></li><li class="tocline"><a class="tocxref" href="#legacy-focusevent-events"><span class="secno">C.2 </span>Legacy <span class="formerLink"><code>FocusEvent</code></span> events</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#legacy-focusevent-event-order"><span class="secno">C.2.1 </span>Legacy FocusEvent event order</a></li></ul></li><li class="tocline"><a class="tocxref" href="#legacy-keyboardevent-events"><span class="secno">C.3 </span>Legacy <span class="formerLink"><code>KeyboardEvent</code></span> events</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#keypress-event-order"><span class="secno">C.3.1 </span><span class="formerLink"><code>keypress</code></span> event order</a></li></ul></li><li class="tocline"><a class="tocxref" href="#legacy-mutationevent-events"><span class="secno">C.4 </span>Legacy <span class="formerLink"><code>MutationEvent</code></span> events</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#interface-MutationEvent"><span class="secno">C.4.1 </span>Interface MutationEvent</a><ul class="toc"></ul></li></ul></li></ul></li><li class="tocline"><a class="tocxref" href="#extending-events"><span class="secno">D. </span>Extending Events</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#extending-events-intro"><span class="secno">D.1 </span>Introduction</a></li><li class="tocline"><a class="tocxref" href="#extending-events-Custom_Events"><span class="secno">D.2 </span>Custom Events</a></li><li class="tocline"><a class="tocxref" href="#extending-events-Impl_Extensions"><span class="secno">D.3 </span>Implementation-Specific Extensions</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#extending-events-prefixes"><span class="secno">D.3.1 </span>Known Implementation-Specific Prefixes</a></li></ul></li></ul></li><li class="tocline"><a class="tocxref" href="#security-considerations"><span class="secno">E. </span>Security Considerations</a></li><li class="tocline"><a class="tocxref" href="#changes-from-earlier-versions"><span class="secno">F. </span>Changes</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#changes-DOMEvents2to3Changes"><span class="secno">F.1 </span>Changes between DOM Level 2 Events and UI Events (formerly DOM Level 3 Events)</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#changes-DOMEvents2to3Changes-flow"><span class="secno">F.1.1 </span>Changes to DOM Level 2 event flow</a></li><li class="tocline"><a class="tocxref" href="#changes-DOMEvents2to3Changes-event-types"><span class="secno">F.1.2 </span>Changes to DOM Level 2 event types</a></li><li class="tocline"><a class="tocxref" href="#changes-DOMLevel2to3Changes"><span class="secno">F.1.3 </span>Changes to DOM Level 2 Events interfaces</a></li><li class="tocline"><a class="tocxref" href="#changes-DOMLevel3Addons"><span class="secno">F.1.4 </span>New Interfaces</a></li></ul></li><li class="tocline"><a class="tocxref" href="#changes-drafts"><span class="secno">F.2 </span>Changes between different drafts of UI Events (formerly DOM Level 3 Events)</a></li></ul></li><li class="tocline"><a class="tocxref" href="#acknowledgements-contributors"><span class="secno">G. </span>Acknowledgements</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#acknowledgements-Productions"><span class="secno">G.1 </span>Production Systems</a></li></ul></li><li class="tocline"><a class="tocxref" href="#glossary"><span class="secno">H. </span>Glossary</a></li><li class="tocline"><a class="tocxref" href="#references"><span class="secno">I. </span>References</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#references-References-Normative"><span class="secno">I.1 </span>Normative References</a></li><li class="tocline"><a class="tocxref" href="#references-References-Informative"><span class="secno">I.2 </span>Informative References</a></li></ul></li></ul></section> <!-- abstract -->
<!-- Section: SOTD ========================================================-->
<!-- sotd -->
<!-- Section 1: UI Events Overview ========================================================-->
<section property="bibo:hasPart" resource="#dom-events-intro" typeof="bibo:Chapter" id="dom-events-intro">
<!--OddPage--><h2 resource="#h-dom-events-intro" id="h-dom-events-intro"><span property="xhv:role" resource="xhv:heading"><span class="secno">1. </span>Introduction</span></h2>
<section property="bibo:hasPart" resource="#dom-events-overview" typeof="bibo:Chapter" id="dom-events-overview">
<h3 resource="#h-dom-events-overview" id="h-dom-events-overview"><span property="xhv:role" resource="xhv:heading"><span class="secno">1.1 </span>Overview</span></h3>
<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 property="bibo:hasPart" resource="#dom-events-conformance" typeof="bibo:Chapter" id="dom-events-conformance">
<h3 resource="#h-dom-events-conformance" id="h-dom-events-conformance"><span property="xhv:role" resource="xhv:heading"><span class="secno">1.2 </span>Conformance</span></h3>
<p><strong>This section is normative.</strong></p>
<p>Within this specification, the key words <q><em title="MUST" class="rfc2119">MUST</em></q>, <q><em title="MUST NOT" class="rfc2119">MUST NOT</em></q>, <q><em title="REQUIRED" class="rfc2119">REQUIRED</em></q>,
<q><em title="SHALL" class="rfc2119">SHALL</em></q>, <q><em title="SHALL NOT" class="rfc2119">SHALL NOT</em></q>, <q><em title="SHOULD" class="rfc2119">SHOULD</em></q>, <q><em title="SHOULD NOT" class="rfc2119">SHOULD NOT</em></q>,
<q><em title="RECOMMENDED" class="rfc2119">RECOMMENDED</em></q>, <q><em title="MAY" class="rfc2119">MAY</em></q>, and <q><em title="OPTIONAL" class="rfc2119">OPTIONAL</em></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 <em title="MUST" class="rfc2119">MUST</em>
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> <em title="MUST" class="rfc2119">MUST</em> 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 <em title="MAY" class="rfc2119">MAY</em> 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 <em title="MUST" class="rfc2119">MUST</em> <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 <em title="MUST" class="rfc2119">MUST</em> support scripting, declarative interactivity, or some other means of
detecting and dispatching events in the manner described by this specification, and <em title="MUST" class="rfc2119">MUST</em> 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 <em title="MAY" class="rfc2119">MAY</em> 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 <em title="MAY" class="rfc2119">MAY</em> 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 <em title="MAY" class="rfc2119">MAY</em> 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 <em title="MUST NOT" class="rfc2119">MUST NOT</em> claim
conformance to UI Events.
Such an implementation which does conform to portions of this specification <em title="MAY" class="rfc2119">MAY</em> claim
conformance to those specific portions.
</p>
<p>A conforming browser <em title="MUST" class="rfc2119">MUST</em> 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 <em title="MUST NOT" class="rfc2119">MUST NOT</em> 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 <em title="SHOULD" class="rfc2119">SHOULD</em> 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 <em title="SHOULD NOT" class="rfc2119">SHOULD NOT</em> use features of this specification marked as
<a class="def" href="#glossary-deprecated">deprecated</a>, but <em title="SHOULD" class="rfc2119">SHOULD</em> rely instead upon
replacement mechanisms defined in this specification and elsewhere.
</p>
<p>Conforming content <em title="MUST" class="rfc2119">MUST</em> use the semantics of the interfaces and
<a class="def" href="#glossary-event-type">event types</a> as described in this specification.
</p>
<div class="note"><div id="h-note1" role="heading" aria-level="4" class="note-title"><span>Note</span></div><p class=""><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></div>
</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 <em title="MAY" class="rfc2119">MAY</em> define additional interfaces and
<a class="def" href="#glossary-event-type">event types</a> appropriate to that specification,
or <em title="MAY" class="rfc2119">MAY</em> 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 <em title="SHOULD NOT" class="rfc2119">SHOULD NOT</em> use or recommend features of this
specification marked as <a class="def" href="#glossary-deprecated">deprecated</a>, but
<em title="SHOULD" class="rfc2119">SHOULD</em> use or recommend the indicated replacement for that the feature (if available).
</p>
</dd>
</dl>
</section> <!-- dom-events-conformance -->
<section property="bibo:hasPart" resource="#style-conventions" typeof="bibo:Chapter" id="style-conventions">
<h3 resource="#h-style-conventions" id="h-style-conventions"><span property="xhv:role" resource="xhv:heading"><span class="secno">1.3 </span>Stylistic Conventions</span></h3>
<p>This specification follows the <a href="http://www.w3.org/People/Schepers/spec-conventions.html">Proposed <abbr title="World Wide Web Consortium">W3C</abbr> 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 title="Key Value" 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 title="Code Value" 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 title="Character Value" class="char">'\u003d'</code> (e.g., the code point
of the key value).
</li>
<li>Glyphs representing character values are shown as: <code title="Character Value Glyph" 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 property="bibo:hasPart" resource="#issues" typeof="bibo:Chapter" id="issues">
<!--OddPage--><h2 resource="#h-issues" id="h-issues"><span property="xhv:role" resource="xhv:heading"><span class="secno">2. </span>Issues</span></h2>
<div class="issue"><div id="h-issue1" role="heading" aria-level="3" class="issue-title"><span>Issue 1</span></div><p class="">Open issues in this specification are called out using this convention.</p></div>
</section>
<!-- Section 3: Architecture ========================================================-->
<section property="bibo:hasPart" resource="#dom-event-architecture" typeof="bibo:Chapter" id="dom-event-architecture">
<!--OddPage--><h2 resource="#h-dom-event-architecture" id="h-dom-event-architecture"><span property="xhv:role" resource="xhv:heading"><span class="secno">3. </span>DOM Event Architecture</span></h2>
<p><em>This section is informative.</em></p>
<section property="bibo:hasPart" resource="#event-flow" typeof="bibo:Chapter" id="event-flow">
<h3 resource="#h-event-flow" id="h-event-flow"><span property="xhv:role" resource="xhv:heading"><span class="secno">3.1 </span>Event dispatch and DOM event flow</span></h3>
<p>This section defines the event <a class="def" href="#glossary-dispatch">dispatch</a> mechanism of the event model defined in this specification.
Applications <em title="MAY" class="rfc2119">MAY</em> dispatch event objects using the <a href="#widl-EventTarget-dispatchEvent"><code>EventTarget.dispatchEvent()</code></a> method, and
implementations <em title="MUST" class="rfc2119">MUST</em> 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="eventflow.svg" alt="Graphical representation of an event dispatched in a DOM tree using the DOM event flow" height="560">
<figcaption>Fig. <span class="figno">1</span> <span class="fig-title">Graphical representation of an event dispatched in a DOM tree using the DOM event flow</span></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 <em title="MUST" class="rfc2119">MUST</em> first determine the event object's <a class="def" href="#glossary-propagation-path">propagation path</a>.</p>
<p>The propagation path <em title="MUST" class="rfc2119">MUST</em> be an ordered list of <a class="def" href="#glossary-current-event-target">current event targets</a> through which
the event object <em title="MUST" class="rfc2119">MUST</em> pass. For DOM implementations, the propagation path <em title="MUST" class="rfc2119">MUST</em> reflect the hierarchical tree
structure of the document. The last item in the list <em title="MUST" class="rfc2119">MUST</em> 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 <em title="MUST NOT" class="rfc2119">MUST NOT</em> 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 <em title="MUST NOT" class="rfc2119">MUST NOT</em> stop the propagation of the event or affect the
<a class="def" href="#glossary-propagation-path">propagation path</a>. The exception itself <em title="MUST NOT" class="rfc2119">MUST NOT</em> 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 <em title="MUST" class="rfc2119">MUST</em> 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 <em title="MUST" class="rfc2119">MUST</em> 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 <em title="MUST" class="rfc2119">MUST</em> be skipped.</p>
<ol>
<li>The <strong id="capture-phase">capture phase</strong>: The event object <em title="MUST" class="rfc2119">MUST</em> 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 <em title="MUST" class="rfc2119">MUST</em> handle the event before it reaches its target.</li>
<li>The <strong id="target-phase">target phase</strong>: The event object <em title="MUST" class="rfc2119">MUST</em> 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 <em title="MUST" class="rfc2119">MUST</em>
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 <em title="MUST NOT" class="rfc2119">MUST NOT</em> bubble, the event object <em title="MUST" class="rfc2119">MUST</em> 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 <em title="MUST" class="rfc2119">MUST</em> handle the event after it has reached its target.</li>
</ol>
<p>Implementations <em title="MUST" class="rfc2119">MUST</em> 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 <em title="MUST" class="rfc2119">MUST</em> determine the <em>current target</em>. This <em title="MUST" class="rfc2119">MUST</em> be the next pending event target in the partial propagation
path, starting with the first. From the perspective of an event listener this <em title="MUST" class="rfc2119">MUST</em> be the event target the listener has been registered on.</p>
<p>Next, the implementation <em title="MUST" class="rfc2119">MUST</em> determine the current target's <a class="def" href="#glossary-candidate-event-handlers">candidate event listeners</a>.
This <em title="MUST" class="rfc2119">MUST</em> 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
<em title="MUST NOT" class="rfc2119">MUST NOT</em> be changed. Adding or removing listeners does not affect the current target's candidate event listeners.</p>
<p>Finally, the implementation <em title="MUST" class="rfc2119">MUST</em> 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> <em title="MUST" class="rfc2119">MUST</em> be set to <code>null</code> and the <a href="#widl-Event-eventPhase"><code>Event.eventPhase</code></a> <em title="MUST" class="rfc2119">MUST</em> 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 <em title="MUST" class="rfc2119">MUST</em> continue to reference the <a class="def" href="#glossary-event-target">
event target</a>).</p>
<p>The model defined above <em title="MUST" class="rfc2119">MUST</em> be applied regardless of the specific event flow associated with an event target. Each event flow <em title="MUST" class="rfc2119">MUST</em> define how the propagation path
<em title="MUST" class="rfc2119">MUST</em> 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 <em title="MUST" class="rfc2119">MUST</em> 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 <em title="MUST" class="rfc2119">MUST</em> 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 <em title="MUST" class="rfc2119">MUST</em> be reentrant. Event listeners <em title="MAY" class="rfc2119">MAY</em> 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 <em title="MUST" class="rfc2119">MUST</em> resume only after the event dispatch of the new event is completed.</p>
</section> <!-- event-flow -->
<section property="bibo:hasPart" resource="#event-flow-default-cancel" typeof="bibo:Chapter" id="event-flow-default-cancel">
<h3 resource="#h-event-flow-default-cancel" id="h-event-flow-default-cancel"><span property="xhv:role" resource="xhv:heading"><span class="secno">3.2 </span>Default actions and cancelable events</span></h3>
<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 <em title="MAY" class="rfc2119">MAY</em> 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 occuring.</p>
</div>
<p><a class="def" href="#glossary-default-action">Default actions</a> <em title="SHOULD" class="rfc2119">SHOULD</em> be performed after the event dispatch has been completed, but in exceptional
cases <em title="MAY" class="rfc2119">MAY</em> 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 <em title="MUST" class="rfc2119">MUST</em> 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 <em title="MUST" class="rfc2119">MUST</em> be undone).
Whether an event object is cancelable <em title="MUST" class="rfc2119">MUST</em> 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>
<div class="note"><div id="h-note2" role="heading" aria-level="4" class="note-title"><span>Note</span></div><p class=""><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></div>