/
dom.html
6014 lines (5888 loc) · 808 KB
/
dom.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 lang="en">
<head>
<meta charset="utf-8">
<meta content="width=device-width, initial-scale=1, shrink-to-fit=no" name="viewport">
<title>DOM Standard</title>
<link href="https://resources.whatwg.org/standard.css" rel="stylesheet">
<link href="https://resources.whatwg.org/bikeshed.css" rel="stylesheet">
<link href="https://resources.whatwg.org/logo-dom.svg" rel="icon">
<meta content="Bikeshed 1.0.0" name="generator">
<style>.highlight .hll { background-color: #ffffcc }
.highlight { background: #ffffff; }
.highlight .c { color: #708090 } /* Comment */
.highlight .k { color: #990055 } /* Keyword */
.highlight .l { color: #000000 } /* Literal */
.highlight .n { color: #0077aa } /* Name */
.highlight .o { color: #999999 } /* Operator */
.highlight .p { color: #999999 } /* Punctuation */
.highlight .cm { color: #708090 } /* Comment.Multiline */
.highlight .cp { color: #708090 } /* Comment.Preproc */
.highlight .c1 { color: #708090 } /* Comment.Single */
.highlight .cs { color: #708090 } /* Comment.Special */
.highlight .kc { color: #990055 } /* Keyword.Constant */
.highlight .kd { color: #990055 } /* Keyword.Declaration */
.highlight .kn { color: #990055 } /* Keyword.Namespace */
.highlight .kp { color: #990055 } /* Keyword.Pseudo */
.highlight .kr { color: #990055 } /* Keyword.Reserved */
.highlight .kt { color: #990055 } /* Keyword.Type */
.highlight .ld { color: #000000 } /* Literal.Date */
.highlight .m { color: #000000 } /* Literal.Number */
.highlight .s { color: #a67f59 } /* Literal.String */
.highlight .na { color: #0077aa } /* Name.Attribute */
.highlight .nc { color: #0077aa } /* Name.Class */
.highlight .no { color: #0077aa } /* Name.Constant */
.highlight .nd { color: #0077aa } /* Name.Decorator */
.highlight .ni { color: #0077aa } /* Name.Entity */
.highlight .ne { color: #0077aa } /* Name.Exception */
.highlight .nf { color: #0077aa } /* Name.Function */
.highlight .nl { color: #0077aa } /* Name.Label */
.highlight .nn { color: #0077aa } /* Name.Namespace */
.highlight .py { color: #0077aa } /* Name.Property */
.highlight .nt { color: #669900 } /* Name.Tag */
.highlight .nv { color: #0077aa } /* Name.Variable */
.highlight .ow { color: #999999 } /* Operator.Word */
.highlight .mb { color: #000000 } /* Literal.Number.Bin */
.highlight .mf { color: #000000 } /* Literal.Number.Float */
.highlight .mh { color: #000000 } /* Literal.Number.Hex */
.highlight .mi { color: #000000 } /* Literal.Number.Integer */
.highlight .mo { color: #000000 } /* Literal.Number.Oct */
.highlight .sb { color: #a67f59 } /* Literal.String.Backtick */
.highlight .sc { color: #a67f59 } /* Literal.String.Char */
.highlight .sd { color: #a67f59 } /* Literal.String.Doc */
.highlight .s2 { color: #a67f59 } /* Literal.String.Double */
.highlight .se { color: #a67f59 } /* Literal.String.Escape */
.highlight .sh { color: #a67f59 } /* Literal.String.Heredoc */
.highlight .si { color: #a67f59 } /* Literal.String.Interpol */
.highlight .sx { color: #a67f59 } /* Literal.String.Other */
.highlight .sr { color: #a67f59 } /* Literal.String.Regex */
.highlight .s1 { color: #a67f59 } /* Literal.String.Single */
.highlight .ss { color: #a67f59 } /* Literal.String.Symbol */
.highlight .vc { color: #0077aa } /* Name.Variable.Class */
.highlight .vg { color: #0077aa } /* Name.Variable.Global */
.highlight .vi { color: #0077aa } /* Name.Variable.Instance */
.highlight .il { color: #000000 } /* Literal.Number.Integer.Long */
.highlight { background: hsl(24, 20%, 95%); }
code.highlight { padding: .1em; border-radius: .3em; }
pre.highlight, pre > code.highlight { display: block; padding: 1em; margin: .5em 0; overflow: auto; border-radius: 0; }
</style>
<body class="h-entry status-LS">
<div class="head">
<p data-fill-with="logo"><a class="logo" href="https://whatwg.org/"> <img alt="WHATWG" height="100" src="https://resources.whatwg.org/logo-dom.svg"> </a> </p>
<h1 class="p-name no-ref allcaps" id="title">DOM</h1>
<h2 class="no-num no-toc no-ref heading settled" id="subtitle"><span class="content">Living Standard — Last Updated <time class="dt-updated" datetime="2016-03-14">14 March 2016</time></span></h2>
<div data-fill-with="spec-metadata">
<dl>
<dt>Participate:
<dd><span><a href="https://github.com/whatwg/dom">GitHub whatwg/dom</a> (<a href="https://github.com/whatwg/dom/issues/new">new issue</a>, <a href="https://github.com/whatwg/dom/issues">open issues</a>, <a href="https://www.w3.org/Bugs/Public/buglist.cgi?component=DOM&product=WebAppsWG&resolution=---">legacy open bugs</a>)</span>
<dd><span><a href="https://wiki.whatwg.org/wiki/IRC">IRC: #whatwg on Freenode</a></span>
<dt>Commits:
<dd><span><a href="https://github.com/whatwg/dom/commits">GitHub whatwg/dom/commits</a></span>
<dd><span><a href="https://twitter.com/thedomstandard">@thedomstandard</a></span>
</dl>
</div>
<div data-fill-with="warning"></div>
</div>
<h2 class="no-num no-toc no-ref heading settled" id="abstract"><span class="content">Abstract</span></h2>
<div class="p-summary" data-fill-with="abstract">
<p>DOM defines a platform-neutral model for events and node trees.</p>
</div>
<div data-fill-with="at-risk"></div>
<nav data-fill-with="table-of-contents" id="toc">
<h2 class="no-num no-toc no-ref" id="contents">Table of Contents</h2>
<ol class="toc" role="directory">
<li><a href="#goals"><span class="secno"></span> <span class="content">Goals</span></a>
<li>
<a href="#conformance"><span class="secno">1</span> <span class="content">Conformance</span></a>
<ol class="toc">
<li><a href="#dependencies"><span class="secno">1.1</span> <span class="content">Dependencies</span></a>
<li><a href="#extensibility"><span class="secno">1.2</span> <span class="content">Extensibility</span></a>
</ol>
<li>
<a href="#terminology"><span class="secno">2</span> <span class="content">Terminology</span></a>
<ol class="toc">
<li><a href="#trees"><span class="secno">2.1</span> <span class="content">Trees</span></a>
<li><a href="#strings"><span class="secno">2.2</span> <span class="content">Strings</span></a>
<li><a href="#ordered sets"><span class="secno">2.3</span> <span class="content">Ordered sets</span></a>
<li><a href="#selectors"><span class="secno">2.4</span> <span class="content">Selectors</span></a>
<li><a href="#namespaces"><span class="secno">2.5</span> <span class="content">Namespaces</span></a>
</ol>
<li>
<a href="#events"><span class="secno">3</span> <span class="content">Events</span></a>
<ol class="toc">
<li><a href="#introduction-to-dom-events"><span class="secno">3.1</span> <span class="content">Introduction to "DOM Events"</span></a>
<li><a href="#interface-event"><span class="secno">3.2</span> <span class="content">Interface <code class="idl"><span>Event</span></code></span></a>
<li><a href="#interface-customevent"><span class="secno">3.3</span> <span class="content">Interface <code class="idl"><span>CustomEvent</span></code></span></a>
<li><a href="#constructing-events"><span class="secno">3.4</span> <span class="content">Constructing events</span></a>
<li><a href="#defining-event-interfaces"><span class="secno">3.5</span> <span class="content">Defining event interfaces</span></a>
<li><a href="#interface-eventtarget"><span class="secno">3.6</span> <span class="content">Interface <code class="idl"><span>EventTarget</span></code></span></a>
<li><a href="#observing-event-listeners"><span class="secno">3.7</span> <span class="content">Observing event listeners</span></a>
<li><a href="#dispatching-events"><span class="secno">3.8</span> <span class="content">Dispatching events</span></a>
<li><a href="#firing-events"><span class="secno">3.9</span> <span class="content">Firing events</span></a>
<li><a href="#action-versus-occurance"><span class="secno">3.10</span> <span class="content">Action versus occurrence</span></a>
</ol>
<li>
<a href="#nodes"><span class="secno">4</span> <span class="content">Nodes</span></a>
<ol class="toc">
<li><a href="#introduction-to-the-dom"><span class="secno">4.1</span> <span class="content">Introduction to "The DOM"</span></a>
<li>
<a href="#node-trees"><span class="secno">4.2</span> <span class="content">Node tree</span></a>
<ol class="toc">
<li><a href="#mutation-algorithms"><span class="secno">4.2.1</span> <span class="content">Mutation algorithms</span></a>
<li><a href="#interface-nonelementparentnode"><span class="secno">4.2.2</span> <span class="content">Interface <code class="idl"><span>NonElementParentNode</span></code></span></a>
<li><a href="#interface-parentnode"><span class="secno">4.2.3</span> <span class="content">Interface <code class="idl"><span>ParentNode</span></code></span></a>
<li><a href="#interface-nondocumenttypechildnode"><span class="secno">4.2.4</span> <span class="content">Interface <code class="idl"><span>NonDocumentTypeChildNode</span></code></span></a>
<li><a href="#interface-childnode"><span class="secno">4.2.5</span> <span class="content">Interface <code class="idl"><span>ChildNode</span></code></span></a>
<li><a href="#element-collections"><span class="secno">4.2.6</span> <span class="content">Collections: <code class="idl"><span>Elements</span></code></span></a>
<li>
<a href="#old-style-collections"><span class="secno">4.2.7</span> <span class="content">Old-style collections: <code class="idl"><span>NodeList</span></code> and <code class="idl"><span>HTMLCollection</span></code></span></a>
<ol class="toc">
<li><a href="#interface-nodelist"><span class="secno">4.2.7.1</span> <span class="content">Interface <code class="idl"><span>NodeList</span></code></span></a>
<li><a href="#interface-htmlcollection"><span class="secno">4.2.7.2</span> <span class="content">Interface <code class="idl"><span>HTMLCollection</span></code></span></a>
</ol>
</ol>
<li>
<a href="#mutation-observers"><span class="secno">4.3</span> <span class="content">Mutation observers</span></a>
<ol class="toc">
<li><a href="#interface-mutationobserver"><span class="secno">4.3.1</span> <span class="content">Interface <code class="idl"><span>MutationObserver</span></code></span></a>
<li><a href="#queueing-a-mutation-record"><span class="secno">4.3.2</span> <span class="content">Queuing a mutation record</span></a>
<li><a href="#interface-mutationrecord"><span class="secno">4.3.3</span> <span class="content">Interface <code class="idl"><span>MutationRecord</span></code></span></a>
<li><a href="#garbage-collection"><span class="secno">4.3.4</span> <span class="content">Garbage collection</span></a>
</ol>
<li><a href="#interface-node"><span class="secno">4.4</span> <span class="content">Interface <code class="idl"><span>Node</span></code></span></a>
<li>
<a href="#interface-document"><span class="secno">4.5</span> <span class="content">Interface <code class="idl"><span>Document</span></code></span></a>
<ol class="toc">
<li><a href="#interface-domimplementation"><span class="secno">4.5.1</span> <span class="content"> Interface <code class="idl"><span>DOMImplementation</span></code></span></a>
</ol>
<li><a href="#interface-documentfragment"><span class="secno">4.6</span> <span class="content">Interface <code class="idl"><span>DocumentFragment</span></code></span></a>
<li><a href="#interface-documenttype"><span class="secno">4.7</span> <span class="content">Interface <code class="idl"><span>DocumentType</span></code></span></a>
<li>
<a href="#interface-element"><span class="secno">4.8</span> <span class="content">Interface <code class="idl"><span>Element</span></code></span></a>
<ol class="toc">
<li><a href="#interface-namednodemap"><span class="secno">4.8.1</span> <span class="content">Interface <code class="idl"><span>NamedNodeMap</span></code></span></a>
<li><a href="#interface-attr"><span class="secno">4.8.2</span> <span class="content">Interface <code class="idl"><span>Attr</span></code></span></a>
</ol>
<li><a href="#interface-characterdata"><span class="secno">4.9</span> <span class="content">Interface <code class="idl"><span>CharacterData</span></code></span></a>
<li><a href="#interface-text"><span class="secno">4.10</span> <span class="content">Interface <code class="idl"><span>Text</span></code></span></a>
<li><a href="#interface-processinginstruction"><span class="secno">4.11</span> <span class="content">Interface <code class="idl"><span>ProcessingInstruction</span></code></span></a>
<li><a href="#interface-comment"><span class="secno">4.12</span> <span class="content">Interface <code class="idl"><span>Comment</span></code></span></a>
</ol>
<li>
<a href="#ranges"><span class="secno">5</span> <span class="content">Ranges</span></a>
<ol class="toc">
<li><a href="#introduction-to-dom-ranges"><span class="secno">5.1</span> <span class="content"> Introduction to "DOM Ranges"</span></a>
<li><a href="#interface-range"><span class="secno">5.2</span> <span class="content"> Interface <code class="idl"><span>Range</span></code></span></a>
</ol>
<li>
<a href="#traversal"><span class="secno">6</span> <span class="content">Traversal</span></a>
<ol class="toc">
<li><a href="#interface-nodeiterator"><span class="secno">6.1</span> <span class="content">Interface <code class="idl"><span>NodeIterator</span></code></span></a>
<li><a href="#interface-treewalker"><span class="secno">6.2</span> <span class="content">Interface <code class="idl"><span>TreeWalker</span></code></span></a>
<li><a href="#interface-nodefilter"><span class="secno">6.3</span> <span class="content">Interface <code class="idl"><span>NodeFilter</span></code></span></a>
</ol>
<li>
<a href="#sets"><span class="secno">7</span> <span class="content">Sets</span></a>
<ol class="toc">
<li><a href="#interface-domtokenlist"><span class="secno">7.1</span> <span class="content">Interface <code class="idl"><span>DOMTokenList</span></code></span></a>
</ol>
<li>
<a href="#historical"><span class="secno">8</span> <span class="content">Historical</span></a>
<ol class="toc">
<li><a href="#dom-events-changes"><span class="secno">8.1</span> <span class="content">DOM Events</span></a>
<li><a href="#dom-core-changes"><span class="secno">8.2</span> <span class="content">DOM Core</span></a>
<li><a href="#dom-ranges-changes"><span class="secno">8.3</span> <span class="content">DOM Ranges</span></a>
<li><a href="#dom-traversal-changes"><span class="secno">8.4</span> <span class="content">DOM Traversal</span></a>
</ol>
<li><a href="#acks"><span class="secno"></span> <span class="content">Acknowledgments</span></a>
<li>
<a href="#index"><span class="secno"></span> <span class="content">Index</span></a>
<ol class="toc">
<li><a href="#index-defined-here"><span class="secno"></span> <span class="content">Terms defined by this specification</span></a>
<li><a href="#index-defined-elsewhere"><span class="secno"></span> <span class="content">Terms defined by reference</span></a>
</ol>
<li>
<a href="#references"><span class="secno"></span> <span class="content">References</span></a>
<ol class="toc">
<li><a href="#normative"><span class="secno"></span> <span class="content">Normative References</span></a>
<li><a href="#informative"><span class="secno"></span> <span class="content">Informative References</span></a>
</ol>
<li><a href="#idl-index"><span class="secno"></span> <span class="content">IDL Index</span></a>
</ol>
</nav>
<main>
<p></p>
<script async="" src="https://resources.whatwg.org/file-issue.js"></script>
<h2 class="no-num heading settled" id="goals"><span class="content">Goals</span></h2>
<p>This specification standardizes the DOM. It does so as follows:</p>
<ol>
<li>
<p>By consolidating <cite>DOM Level 3 Core</cite> <a data-link-type="biblio" href="#biblio-dom-level-3-core">[DOM-Level-3-Core]</a>, <cite>Element Traversal</cite> <a data-link-type="biblio" href="#biblio-elementtraversal">[ELEMENTTRAVERSAL]</a>, <cite>Selectors API Level 2</cite> <a data-link-type="biblio" href="#biblio-selectors-api2">[SELECTORS-API2]</a>, the
"DOM Event Architecture" and "Basic Event Interfaces" chapters of <cite>DOM Level 3 Events</cite> <a data-link-type="biblio" href="#biblio-uievents-20031107">[uievents-20031107]</a> (specific types of events do not
belong in the DOM Standard), and <cite>DOM Level 2 Traversal and Range</cite> <a data-link-type="biblio" href="#biblio-dom-level-2-traversal-range">[DOM-Level-2-Traversal-Range]</a>, and: </p>
<ul class="brief">
<li>Aligning them with the JavaScript ecosystem where possible.
<li>Aligning them with existing implementations.
<li>Simplifying them as much as possible.
</ul>
<li>
<p>By moving features from the HTML Standard <a data-link-type="biblio" href="#biblio-html">[HTML]</a> that make more sense to be
specified as part of the DOM Standard. </p>
<li>
<p>By defining a replacement for the "Mutation Events" and
"Mutation Name Event Types" chapters of <cite>DOM Level 3 Events</cite> <a data-link-type="biblio" href="#biblio-uievents-20031107">[uievents-20031107]</a> as the old model
was problematic. </p>
<p class="note no-backref" role="note">The old model is expected to be removed from implementations
in due course. </p>
<li>
<p>By defining new features that simplify common DOM operations. </p>
</ol>
<h2 class="heading settled" data-level="1" id="conformance"><span class="secno">1. </span><span class="content">Conformance</span><a class="self-link" href="#conformance"></a></h2>
<p>All diagrams, examples, and notes in this specification are
non-normative, as are all sections explicitly marked non-normative.
Everything else in this specification is normative.</p>
<p>The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in RFC 2119.
For readability, these words do not appear in all uppercase letters in this
specification. <a data-link-type="biblio" href="#biblio-rfc2119">[RFC2119]</a></p>
<p>Requirements phrased in the imperative as part of algorithms
(such as "strip any leading space characters" or "return false and
terminate these steps") are to be interpreted with the meaning of the
keyword ("must", "should", "may", etc.) used in introducing the
algorithm.</p>
<p>Conformance requirements phrased as algorithms or specific steps
may be implemented in any manner, so long as the end result is
equivalent. (In particular, the algorithms defined in this
specification are intended to be easy to follow, and not intended to
be performant.)</p>
<p id="hardwareLimitations">User agents may impose
implementation-specific limits on otherwise unconstrained inputs,
e.g. to prevent denial of service attacks, to guard against running
out of memory, or to work around platform-specific limitations. </p>
<p>When a method or an attribute is said to call another method or attribute, the user agent must invoke its internal API for that attribute or method so that e.g. the author can’t change the behavior by overriding attributes or methods with custom properties or functions in JavaScript.</p>
<p>Unless otherwise stated, string comparisons are done in a <a data-link-type="dfn" href="#case-sensitive">case-sensitive</a> manner.</p>
<h3 class="heading settled" data-level="1.1" id="dependencies"><span class="secno">1.1. </span><span class="content">Dependencies</span><a class="self-link" href="#dependencies"></a></h3>
<p>The IDL fragments in this specification must be interpreted as
required for conforming IDL fragments, as described in the Web IDL
specification. <a data-link-type="biblio" href="#biblio-webidl">[WEBIDL]</a></p>
<p>Some of the terms used in this specification are defined in <cite>Encoding</cite>, <cite>Selectors</cite>, <cite>Web IDL</cite>, <cite>XML</cite>, and <cite>Namespaces in XML</cite>. <a data-link-type="biblio" href="#biblio-whatwg-encoding">[ENCODING]</a> <a data-link-type="biblio" href="#biblio-selectors4">[SELECTORS4]</a> <a data-link-type="biblio" href="#biblio-webidl">[WEBIDL]</a> <a data-link-type="biblio" href="#biblio-xml">[XML]</a> <a data-link-type="biblio" href="#biblio-xml-names">[XML-NAMES]</a></p>
<h3 class="heading settled" data-level="1.2" id="extensibility"><span class="secno">1.2. </span><span class="content">Extensibility</span><a class="self-link" href="#extensibility"></a></h3>
<p>Vendor-specific proprietary extensions to this specification are
strongly discouraged. Authors must not use such extensions, as
doing so reduces interoperability and fragments the user base,
allowing only users of specific user agents to access the content in
question.</p>
<p>When extensions are needed, the DOM Standard can be updated accordingly, or a new standard
can be written that hooks into the provided extensibility hooks for <dfn data-dfn-type="dfn" data-export="" data-lt="other applicable specifications" id="other-applicable-specifications">applicable specifications<a class="self-link" href="#other-applicable-specifications"></a></dfn>.</p>
<h2 class="heading settled" data-level="2" id="terminology"><span class="secno">2. </span><span class="content">Terminology</span><a class="self-link" href="#terminology"></a></h2>
<p>The term <dfn data-dfn-type="dfn" data-export="" id="context-object">context object<a class="self-link" href="#context-object"></a></dfn> means the object on which the algorithm,
attribute getter, attribute setter, or method being discussed was called. When the <a data-link-type="dfn" href="#context-object">context object</a> is unambiguous, the term can be omitted.</p>
<h3 class="heading settled" data-level="2.1" id="trees"><span class="secno">2.1. </span><span class="content">Trees</span><a class="self-link" href="#trees"></a></h3>
<p>A <dfn data-dfn-type="dfn" data-export="" id="concept-tree">tree<a class="self-link" href="#concept-tree"></a></dfn> is a finite hierarchical tree structure. In <dfn data-dfn-type="dfn" data-export="" id="concept-tree-order">tree order<a class="self-link" href="#concept-tree-order"></a></dfn> is preorder, depth-first
traversal of a <a data-link-type="dfn" href="#concept-tree">tree</a>.</p>
<p>An object that <dfn data-dfn-for="tree" data-dfn-type="dfn" data-export="" data-lt="participate" id="concept-tree-participate">participates<a class="self-link" href="#concept-tree-participate"></a></dfn> in
a <a data-link-type="dfn" href="#concept-tree">tree</a> has a <dfn data-dfn-for="tree" data-dfn-type="dfn" data-export="" id="concept-tree-parent">parent<a class="self-link" href="#concept-tree-parent"></a></dfn>, which is either another object
or null, and an ordered list of zero or more <dfn data-dfn-for="tree" data-dfn-type="dfn" data-export="" data-lt="child|children" id="concept-tree-child">child<a class="self-link" href="#concept-tree-child"></a></dfn> objects. An object <var>A</var> whose <a data-link-type="dfn" href="#concept-tree-parent">parent</a> is object <var>B</var> is a <a data-link-type="dfn" href="#concept-tree-child">child</a> of <var>B</var>.</p>
<p>The <dfn data-dfn-for="tree" data-dfn-type="dfn" data-export="" id="concept-tree-root">root<a class="self-link" href="#concept-tree-root"></a></dfn> of an object is itself, if its <a data-link-type="dfn" href="#concept-tree-parent">parent</a> is null, or else it is the <a data-link-type="dfn" href="#concept-tree-root">root</a> of its <a data-link-type="dfn" href="#concept-tree-parent">parent</a>.</p>
<p>An object <var>A</var> is called a <dfn data-dfn-for="tree" data-dfn-type="dfn" data-export="" id="concept-tree-descendant">descendant<a class="self-link" href="#concept-tree-descendant"></a></dfn> of an object <var>B</var>, if either <var>A</var> is a <a data-link-type="dfn" href="#concept-tree-child">child</a> of <var>B</var> or <var>A</var> is a <a data-link-type="dfn" href="#concept-tree-child">child</a> of an
object <var>C</var> that is a <a data-link-type="dfn" href="#concept-tree-descendant">descendant</a> of <var>B</var>.</p>
<p>An <dfn data-dfn-for="tree" data-dfn-type="dfn" data-export="" id="concept-tree-inclusive-descendant">inclusive descendant<a class="self-link" href="#concept-tree-inclusive-descendant"></a></dfn> is
an object or one of its <a data-link-type="dfn" href="#concept-tree-descendant">descendants</a>.</p>
<p>An object <var>A</var> is called an <dfn data-dfn-for="tree" data-dfn-type="dfn" data-export="" id="concept-tree-ancestor">ancestor<a class="self-link" href="#concept-tree-ancestor"></a></dfn> of an object <var>B</var> if and only if <var>B</var> is a <a data-link-type="dfn" href="#concept-tree-descendant">descendant</a> of <var>A</var>.</p>
<p>An <dfn data-dfn-for="tree" data-dfn-type="dfn" data-export="" id="concept-tree-inclusive-ancestor">inclusive ancestor<a class="self-link" href="#concept-tree-inclusive-ancestor"></a></dfn> is
an object or one of its <a data-link-type="dfn" href="#concept-tree-ancestor">ancestors</a>.</p>
<p>An object <var>A</var> is called a <dfn data-dfn-for="tree" data-dfn-type="dfn" data-export="" id="concept-tree-sibling">sibling<a class="self-link" href="#concept-tree-sibling"></a></dfn> of an object <var>B</var>, if and only if <var>B</var> and <var>A</var> share the same non-null <a data-link-type="dfn" href="#concept-tree-parent">parent</a>.</p>
<p>An <dfn data-dfn-for="tree" data-dfn-type="dfn" data-export="" id="concept-tree-inclusive-sibling">inclusive sibling<a class="self-link" href="#concept-tree-inclusive-sibling"></a></dfn> is an
object or one of its <a data-link-type="dfn" href="#concept-tree-sibling">siblings</a>.</p>
<p>An object <var>A</var> is <dfn data-dfn-for="tree" data-dfn-type="dfn" data-export="" id="concept-tree-preceding">preceding<a class="self-link" href="#concept-tree-preceding"></a></dfn> an object <var>B</var> if <var>A</var> and <var>B</var> are in the
same <a data-link-type="dfn" href="#concept-tree">tree</a> and <var>A</var> comes
before <var>B</var> in <a data-link-type="dfn" href="#concept-tree-order">tree order</a>.</p>
<p>An object <var>A</var> is <dfn data-dfn-for="tree" data-dfn-type="dfn" data-export="" id="concept-tree-following">following<a class="self-link" href="#concept-tree-following"></a></dfn> an object <var>B</var> if <var>A</var> and <var>B</var> are in the
same <a data-link-type="dfn" href="#concept-tree">tree</a> and <var>A</var> comes
after <var>B</var> in <a data-link-type="dfn" href="#concept-tree-order">tree order</a>.</p>
<p>The <dfn data-dfn-for="tree" data-dfn-type="dfn" data-export="" id="concept-tree-first-child">first child<a class="self-link" href="#concept-tree-first-child"></a></dfn> of an object is its
first <a data-link-type="dfn" href="#concept-tree-child">child</a> or null if it has no <a data-link-type="dfn" href="#concept-tree-child">children</a>.</p>
<p>The <dfn data-dfn-for="tree" data-dfn-type="dfn" data-export="" id="concept-tree-last-child">last child<a class="self-link" href="#concept-tree-last-child"></a></dfn> of an object is its
last <a data-link-type="dfn" href="#concept-tree-child">child</a> or null if it has no <a data-link-type="dfn" href="#concept-tree-child">children</a>.</p>
<p>The <dfn data-dfn-for="tree" data-dfn-type="dfn" data-export="" id="concept-tree-previous-sibling">previous sibling<a class="self-link" href="#concept-tree-previous-sibling"></a></dfn> of an
object is its first <a data-link-type="dfn" href="#concept-tree-preceding">preceding</a> <a data-link-type="dfn" href="#concept-tree-sibling">sibling</a> or null if it has no <a data-link-type="dfn" href="#concept-tree-preceding">preceding</a> <a data-link-type="dfn" href="#concept-tree-sibling">sibling</a>.</p>
<p>The <dfn data-dfn-for="tree" data-dfn-type="dfn" data-export="" id="concept-tree-next-sibling">next sibling<a class="self-link" href="#concept-tree-next-sibling"></a></dfn> of an
object is its first <a data-link-type="dfn" href="#concept-tree-following">following</a> <a data-link-type="dfn" href="#concept-tree-sibling">sibling</a> or null if it has no <a data-link-type="dfn" href="#concept-tree-following">following</a> <a data-link-type="dfn" href="#concept-tree-sibling">sibling</a>.</p>
<p>The <dfn data-dfn-for="tree" data-dfn-type="dfn" data-export="" id="concept-tree-index">index<a class="self-link" href="#concept-tree-index"></a></dfn> of an object is its number
of <a data-link-type="dfn" href="#concept-tree-preceding">preceding</a> <a data-link-type="dfn" href="#concept-tree-sibling">siblings</a>.</p>
<h3 class="heading settled" data-level="2.2" id="strings"><span class="secno">2.2. </span><span class="content">Strings</span><a class="self-link" href="#strings"></a></h3>
<p>Comparing two strings in a <dfn data-dfn-type="dfn" data-export="" data-lt="case-sensitive|case-sensitively" id="case-sensitive">case-sensitive<a class="self-link" href="#case-sensitive"></a></dfn> manner means
comparing them exactly, code point for code point.</p>
<p>Comparing two strings in a <dfn data-dfn-type="dfn" data-export="" data-lt="ASCII case-insensitive|ASCII case-insensitively" id="ascii-case-insensitive">ASCII case-insensitive<a class="self-link" href="#ascii-case-insensitive"></a></dfn> manner means comparing them exactly, code point for code point, except that the characters
in the range U+0041 to U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z),
inclusive, and the corresponding characters in the range U+0061 to U+007A (i.e.
LATIN SMALL LETTER A to LATIN SMALL LETTER Z), inclusive, are considered to also match.</p>
<p><dfn data-dfn-type="dfn" data-export="" data-lt="converted to ASCII uppercase" id="converted-to-ascii-uppercase">Converting a string to ASCII uppercase<a class="self-link" href="#converted-to-ascii-uppercase"></a></dfn> means replacing all characters in the range U+0061 to U+007A, inclusive, with the
corresponding characters in the range U+0041 to U+005A, inclusive.</p>
<p><dfn data-dfn-type="dfn" data-export="" data-lt="converted to ASCII lowercase" id="converted-to-ascii-lowercase">Converting a string to ASCII lowercase<a class="self-link" href="#converted-to-ascii-lowercase"></a></dfn> means replacing all characters in the range U+0041 to U+005A, inclusive, with the
corresponding characters in the range U+0061 to U+007A, inclusive.</p>
<p>A string <var>pattern</var> is a <dfn data-dfn-type="dfn" data-export="" id="prefix-match">prefix match<a class="self-link" href="#prefix-match"></a></dfn> for a string <var>s</var> when <var>pattern</var> is not longer than <var>s</var> and truncating <var>s</var> to <var>pattern</var>’s length leaves the two strings as matches of each other.</p>
<h3 class="heading settled" data-level="2.3" id="ordered sets"><span class="secno">2.3. </span><span class="content">Ordered sets</span><a class="self-link" href="#ordered%20sets"></a></h3>
<p>The <dfn data-dfn-type="dfn" data-export="" id="concept-ordered-set-parser">ordered set parser<a class="self-link" href="#concept-ordered-set-parser"></a></dfn> takes a string <var>input</var> and then runs these steps:</p>
<ol>
<li>Let <var>position</var> be a pointer into <var>input</var>,
initially pointing at the start of the string.
<li>Let <var>tokens</var> be an ordered set of tokens, initially empty.
<li><a data-link-type="dfn" href="#skip-ascii-whitespace">Skip ASCII whitespace</a>.
<li>
While <var>position</var> is not past the end of <var>input</var>:
<ol>
<li><a data-link-type="dfn" href="#collect-a-code-point-sequence">Collect a code point sequence</a> of code points that are
not <a data-link-type="dfn" href="https://encoding.spec.whatwg.org/#ascii-whitespace">ASCII whitespace</a>.
<li>If the collected string is not in <var>tokens</var>, append the
collected string to <var>tokens</var>.
<li><a data-link-type="dfn" href="#skip-ascii-whitespace">Skip ASCII whitespace</a>.
</ol>
<li>Return <var>tokens</var>.
</ol>
<p>To <dfn data-dfn-type="dfn" data-export="" id="collect-a-code-point-sequence">collect a code point sequence<a class="self-link" href="#collect-a-code-point-sequence"></a></dfn> of <var>code points</var>, run these steps:</p>
<ol>
<li>Let <var>input</var> and <var>position</var> be the same
variables as those of the same name in the algorithm that invoked these
steps.
<li>Let <var>result</var> be the empty string.
<li>While <var>position</var> does not point past the end of <var>input</var> and the code point at <var>position</var> is
one of <var>code points</var>, append that code point to the end
of <var>result</var> and advance <var>position</var> to the
next code point in <var>input</var>.
<li>Return <var>result</var>.
</ol>
<p>To <dfn data-dfn-type="dfn" data-export="" id="skip-ascii-whitespace">skip ASCII whitespace<a class="self-link" href="#skip-ascii-whitespace"></a></dfn> means to <a data-link-type="dfn" href="#collect-a-code-point-sequence">collect a code point sequence</a> of <a data-link-type="dfn" href="https://encoding.spec.whatwg.org/#ascii-whitespace">ASCII whitespace</a> and discard the
return value.</p>
<p>The <dfn data-dfn-type="dfn" data-export="" id="concept-ordered-set-serializer">ordered set serializer<a class="self-link" href="#concept-ordered-set-serializer"></a></dfn> takes a <var>set</var> and returns the concatenation of the strings in <var>set</var>, separated from each other by U+0020, if <var>set</var> is non-empty, and the empty string otherwise.</p>
<h3 class="heading settled" data-level="2.4" id="selectors"><span class="secno">2.4. </span><span class="content">Selectors</span><a class="self-link" href="#selectors"></a></h3>
<p>To <dfn data-dfn-type="dfn" data-export="" id="match-a-relative-selectors-string">match a relative selectors string<a class="self-link" href="#match-a-relative-selectors-string"></a></dfn> <var>relativeSelectors</var> against a <var>set</var>, run these steps:</p>
<ol>
<li>Let <var>s</var> be the result of <a data-link-type="dfn" href="https://drafts.csswg.org/selectors-4/#parse-a-relative-selector">parse a relative selector</a> from <var>relativeSelectors</var> against <var>set</var>. <a data-link-type="biblio" href="#biblio-selectors4">[SELECTORS4]</a>
<li>If <var>s</var> is failure, <a data-link-type="dfn" href="https://heycam.github.io/webidl/#dfn-throw">throw</a> a <code class="idl"><a data-link-type="idl" href="https://heycam.github.io/webidl/#syntaxerror">SyntaxError</a></code>.
<li>Return the result of <a data-link-type="dfn" href="https://drafts.csswg.org/selectors-4/#evaluate-a-selector">evaluate a selector</a> <var>s</var> using <a data-link-type="dfn" href="https://drafts.csswg.org/selectors-4/#scope-element">:scope elements</a> <var>set</var>. <a data-link-type="biblio" href="#biblio-selectors4">[SELECTORS4]</a>
</ol>
<p>To <dfn data-dfn-type="dfn" data-export="" id="scope-match-a-selectors-string">scope-match a selectors string<a class="self-link" href="#scope-match-a-selectors-string"></a></dfn> <var>selectors</var> against a <var>node</var>, run these steps:</p>
<ol>
<li>Let <var>s</var> be the result of <a data-link-type="dfn" href="https://drafts.csswg.org/selectors-4/#parse-a-selector">parse a selector</a> <var>selectors</var>. <a data-link-type="biblio" href="#biblio-selectors4">[SELECTORS4]</a>
<li>If <var>s</var> is failure, <a data-link-type="dfn" href="https://heycam.github.io/webidl/#dfn-throw">throw</a> a <code class="idl"><a data-link-type="idl" href="https://heycam.github.io/webidl/#syntaxerror">SyntaxError</a></code>.
<li>Return the result of <a data-link-type="dfn" href="https://drafts.csswg.org/selectors-4/#evaluate-a-selector">evaluate a selector</a> <var>s</var> against <var>node</var>’s <a data-link-type="dfn" href="#concept-tree-root">root</a> using <a data-link-type="dfn" href="https://drafts.csswg.org/selectors-4/#scoping-root">scoping root</a> <var>node</var> and
scoping method <a data-link-type="dfn" href="https://drafts.csswg.org/selectors-4/#scope-filtered">scope-filtered</a>. <a data-link-type="biblio" href="#biblio-selectors4">[SELECTORS4]</a>.
</ol>
<p class="note" role="note">Support for namespaces within selectors is not planned and will not be
added. </p>
<h3 class="heading settled" data-level="2.5" id="namespaces"><span class="secno">2.5. </span><span class="content">Namespaces</span><a class="self-link" href="#namespaces"></a></h3>
<p>The <dfn data-dfn-type="dfn" data-export="" id="html-namespace">HTML namespace<a class="self-link" href="#html-namespace"></a></dfn> is <code>http://www.w3.org/1999/xhtml</code>.</p>
<p>The <dfn data-dfn-type="dfn" data-export="" id="xml-namespace">XML namespace<a class="self-link" href="#xml-namespace"></a></dfn> is <code>http://www.w3.org/XML/1998/namespace</code>.</p>
<p>The <dfn data-dfn-type="dfn" data-export="" id="xmlns-namespace">XMLNS namespace<a class="self-link" href="#xmlns-namespace"></a></dfn> is <code>http://www.w3.org/2000/xmlns/</code>.</p>
<p>To <dfn data-dfn-type="dfn" data-export="" id="validate">validate<a class="self-link" href="#validate"></a></dfn> a <var>qualifiedName</var>, run these steps:</p>
<ol>
<li>If <var>qualifiedName</var> does not match the <code><a class="css" data-link-type="type" href="https://www.w3.org/TR/xml/#NT-Name">Name</a></code> production, <a data-link-type="dfn" href="https://heycam.github.io/webidl/#dfn-throw">throw</a> an <code class="idl"><a data-link-type="idl" href="https://heycam.github.io/webidl/#invalidcharactererror">InvalidCharacterError</a></code> exception.
<li>If <var>qualifiedName</var> does not match the <code><a class="css" data-link-type="type" href="https://www.w3.org/TR/xml-names/#NT-QName">QName</a></code> production, <a data-link-type="dfn" href="https://heycam.github.io/webidl/#dfn-throw">throw</a> a <code class="idl"><a data-link-type="idl" href="https://heycam.github.io/webidl/#namespaceerror">NamespaceError</a></code> exception.
</ol>
<p>To <dfn data-dfn-type="dfn" data-export="" id="validate-and-extract">validate and extract<a class="self-link" href="#validate-and-extract"></a></dfn> a <var>namespace</var> and <var>qualifiedName</var>,
run these steps:</p>
<ol>
<li>If <var>namespace</var> is the empty string, set it to null.
<li><a data-link-type="dfn" href="#validate">Validate</a> <var>qualifiedName</var>. Rethrow any exceptions.
<li>Let <var>prefix</var> be null.
<li>Let <var>localName</var> be <var>qualifiedName</var>.
<li>If <var>qualifiedName</var> contains a "<code>:</code>" (U+003E), then split the
string on it and set <var>prefix</var> to the part before and <var>localName</var> to
the part after.
<li>If <var>prefix</var> is non-null and <var>namespace</var> is null, <a data-link-type="dfn" href="https://heycam.github.io/webidl/#dfn-throw">throw</a> a <code class="idl"><a data-link-type="idl" href="https://heycam.github.io/webidl/#namespaceerror">NamespaceError</a></code> exception.
<li>If <var>prefix</var> is "<code>xml</code>" and <var>namespace</var> is
not the <a data-link-type="dfn" href="#xml-namespace">XML namespace</a>, <a data-link-type="dfn" href="https://heycam.github.io/webidl/#dfn-throw">throw</a> a <code class="idl"><a data-link-type="idl" href="https://heycam.github.io/webidl/#namespaceerror">NamespaceError</a></code> exception.
<li>If either <var>qualifiedName</var> or <var>prefix</var> is
"<code>xmlns</code>" and <var>namespace</var> is not the <a data-link-type="dfn" href="#xmlns-namespace">XMLNS namespace</a>, <a data-link-type="dfn" href="https://heycam.github.io/webidl/#dfn-throw">throw</a> a <code class="idl"><a data-link-type="idl" href="https://heycam.github.io/webidl/#namespaceerror">NamespaceError</a></code> exception.
<li>If <var>namespace</var> is the <a data-link-type="dfn" href="#xmlns-namespace">XMLNS namespace</a> and neither <var>qualifiedName</var> nor <var>prefix</var> is "<code>xmlns</code>", <a data-link-type="dfn" href="https://heycam.github.io/webidl/#dfn-throw">throw</a> a <code class="idl"><a data-link-type="idl" href="https://heycam.github.io/webidl/#namespaceerror">NamespaceError</a></code> exception.
<li>Return <var>namespace</var>, <var>prefix</var>, and <var>localName</var>.
</ol>
<h2 class="heading settled" data-level="3" id="events"><span class="secno">3. </span><span class="content">Events</span><a class="self-link" href="#events"></a></h2>
<h3 class="heading settled" data-level="3.1" id="introduction-to-dom-events"><span class="secno">3.1. </span><span class="content">Introduction to "DOM Events"</span><a class="self-link" href="#introduction-to-dom-events"></a></h3>
<p>Throughout the web platform <a data-link-type="dfn" href="#concept-event">events</a> are <a data-link-type="dfn" href="#concept-event-dispatch">dispatched</a> to objects to signal an
occurrence, such as network activity or user interaction. These objects implement the <code class="idl"><a data-link-type="idl" href="#eventtarget">EventTarget</a></code> interface and can therefore add <a data-link-type="dfn" href="#concept-event-listener">event listeners</a> to observe <a data-link-type="dfn" href="#concept-event">events</a> by calling <code class="idl"><a data-link-type="idl" href="#dom-eventtarget-addeventlistener">addEventListener()</a></code>:</p>
<pre class="lang-javascript highlight"><span class="nx">obj</span><span class="p">.</span><span class="nx">addEventListener</span><span class="p">(</span><span class="s2">"load"</span><span class="p">,</span> <span class="nx">imgFetched</span><span class="p">)</span>
<span class="kd">function</span> <span class="nx">imgFetched</span><span class="p">(</span><span class="nx">ev</span><span class="p">)</span> <span class="p">{</span>
<span class="c1">// great success</span>
<span class="err">…</span>
<span class="p">}</span></pre>
<p><a data-link-type="dfn" href="#concept-event-listener">Event listeners</a> can be removed
by utilizing the <code class="idl"><a data-link-type="idl" href="#dom-eventtarget-removeeventlistener">removeEventListener()</a></code> method, passing the same arguments.</p>
<p><a data-link-type="dfn" href="#concept-event">Events</a> are objects too and implement the <code class="idl"><a data-link-type="idl" href="#event">Event</a></code> interface (or a derived interface). In the example above <var>ev</var> is the <a data-link-type="dfn" href="#concept-event">event</a>. It is
passed as argument to <a data-link-type="dfn" href="#concept-event-listener">event listener</a>’s <b>callback</b> (typically a JavaScript Function as shown above). <a data-link-type="dfn" href="#concept-event-listener">Event listeners</a> key off the <a data-link-type="dfn" href="#concept-event">event</a>’s <code class="idl"><a data-link-type="idl" href="#dom-event-type">type</a></code> attribute value
("<code>load</code>" in the above example). The <a data-link-type="dfn" href="#concept-event">event</a>’s <code class="idl"><a data-link-type="idl" href="#dom-event-target">target</a></code> attribute value returns the
object to which the <a data-link-type="dfn" href="#concept-event">event</a> was <a data-link-type="dfn" href="#concept-event-dispatch">dispatched</a> (<var>obj</var> above).</p>
<p>Now while typically <a data-link-type="dfn" href="#concept-event">events</a> are <a data-link-type="dfn" href="#concept-event-dispatch">dispatched</a> by the user agent as
the result of user interaction or the completion of some task, applications
can <a data-link-type="dfn" href="#concept-event-dispatch">dispatch</a> <a data-link-type="dfn" href="#concept-event">events</a> themselves, commonly known as
synthetic events:</p>
<pre class="lang-javascript highlight"><span class="c1">// add an appropriate event listener</span>
<span class="nx">obj</span><span class="p">.</span><span class="nx">addEventListener</span><span class="p">(</span><span class="s2">"cat"</span><span class="p">,</span> <span class="kd">function</span><span class="p">(</span><span class="nx">e</span><span class="p">)</span> <span class="p">{</span> <span class="nx">process</span><span class="p">(</span><span class="nx">e</span><span class="p">.</span><span class="nx">detail</span><span class="p">)</span> <span class="p">})</span>
<span class="c1">// create and dispatch the event</span>
<span class="kd">var</span> <span class="nx">event</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">CustomEvent</span><span class="p">(</span><span class="s2">"cat"</span><span class="p">,</span> <span class="p">{</span><span class="s2">"detail"</span><span class="o">:</span><span class="p">{</span><span class="s2">"hazcheeseburger"</span><span class="o">:</span><span class="kc">true</span><span class="p">}})</span>
<span class="nx">obj</span><span class="p">.</span><span class="nx">dispatchEvent</span><span class="p">(</span><span class="nx">event</span><span class="p">)</span></pre>
<p>Apart from signaling, <a data-link-type="dfn" href="#concept-event">events</a> are
sometimes also used to let an application control what happens next in an
operation. For instance as part of form submission an <a data-link-type="dfn" href="#concept-event">event</a> whose <code class="idl"><a data-link-type="idl" href="#dom-event-type">type</a></code> attribute value is
"<code>submit</code>" is <a data-link-type="dfn" href="#concept-event-dispatch">dispatched</a>. If this <a data-link-type="dfn" href="#concept-event">event</a>’s <code class="idl"><a data-link-type="idl" href="#dom-event-preventdefault">preventDefault()</a></code> method is
invoked, form submission will be terminated. Applications who wish to make
use of this functionality through <a data-link-type="dfn" href="#concept-event">events</a> <a data-link-type="dfn" href="#concept-event-dispatch">dispatched</a> by the application
(synthetic events) can make use of the return value of the <code class="idl"><a data-link-type="idl" href="#dom-eventtarget-dispatchevent">dispatchEvent()</a></code> method:</p>
<pre class="lang-javascript highlight"><span class="k">if</span><span class="p">(</span><span class="nx">obj</span><span class="p">.</span><span class="nx">dispatchEvent</span><span class="p">(</span><span class="nx">event</span><span class="p">))</span> <span class="p">{</span>
<span class="c1">// event was not canceled, time for some magic</span>
<span class="err">…</span>
<span class="p">}</span></pre>
<p>When an <a data-link-type="dfn" href="#concept-event">event</a> is <a data-link-type="dfn" href="#concept-event-dispatch">dispatched</a> to an object that <a data-link-type="dfn" href="#concept-tree-participate">participates</a> in a <a data-link-type="dfn" href="#concept-tree">tree</a> (e.g. an <a data-link-type="dfn" href="#concept-element">element</a>), it can reach <a data-link-type="dfn" href="#concept-event-listener">event listeners</a> on that object’s <a data-link-type="dfn" href="#concept-tree-ancestor">ancestors</a> too. First all object’s <a data-link-type="dfn" href="#concept-tree-ancestor">ancestor</a> <a data-link-type="dfn" href="#concept-event-listener">event listeners</a> whose <b>capture</b> variable is set to true are invoked, in <a data-link-type="dfn" href="#concept-tree-order">tree order</a>. Second, object’s own <a data-link-type="dfn" href="#concept-event-listener">event listeners</a> are invoked. And
finally, and only if <a data-link-type="dfn" href="#concept-event">event</a>’s <code class="idl"><a data-link-type="idl" href="#dom-event-bubbles">bubbles</a></code> attribute value is true,
object’s <a data-link-type="dfn" href="#concept-tree-ancestor">ancestor</a> <a data-link-type="dfn" href="#concept-event-listener">event listeners</a> are invoked again,
but now in reverse <a data-link-type="dfn" href="#concept-tree-order">tree order</a>.</p>
<p>Lets look at an example of how <a data-link-type="dfn" href="#concept-event">events</a> work in a <a data-link-type="dfn" href="#concept-tree">tree</a>:</p>
<pre class="lang-markup highlight"><span class="cp"><!doctype html></span>
<span class="nt"><html></span>
<span class="nt"><head></span>
<span class="nt"><title></span>Boring example<span class="nt"></title></span>
<span class="nt"></head></span>
<span class="nt"><body></span>
<span class="nt"><p></span>Hello <span class="nt"><span</span> <span class="na">id=</span><span class="s">x</span><span class="nt">></span>world<span class="nt"></span></span>!<span class="nt"></p></span>
<span class="nt"><script></span>
<span class="kd">function</span> <span class="nx">test</span><span class="p">(</span><span class="nx">e</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">debug</span><span class="p">(</span><span class="nx">e</span><span class="p">.</span><span class="nx">target</span><span class="p">,</span> <span class="nx">e</span><span class="p">.</span><span class="nx">currentTarget</span><span class="p">,</span> <span class="nx">e</span><span class="p">.</span><span class="nx">eventPhase</span><span class="p">)</span>
<span class="p">}</span>
<span class="nb">document</span><span class="p">.</span><span class="nx">addEventListener</span><span class="p">(</span><span class="s2">"hey"</span><span class="p">,</span> <span class="nx">test</span><span class="p">,</span> <span class="p">{</span><span class="nx">capture</span><span class="o">:</span> <span class="kc">true</span><span class="p">})</span>
<span class="nb">document</span><span class="p">.</span><span class="nx">body</span><span class="p">.</span><span class="nx">addEventListener</span><span class="p">(</span><span class="s2">"hey"</span><span class="p">,</span> <span class="nx">test</span><span class="p">)</span>
<span class="kd">var</span> <span class="nx">ev</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">Event</span><span class="p">(</span><span class="s2">"hey"</span><span class="p">,</span> <span class="p">{</span><span class="nx">bubbles</span><span class="o">:</span><span class="kc">true</span><span class="p">})</span>
<span class="nb">document</span><span class="p">.</span><span class="nx">getElementById</span><span class="p">(</span><span class="s2">"x"</span><span class="p">).</span><span class="nx">dispatchEvent</span><span class="p">(</span><span class="nx">ev</span><span class="p">)</span>
<span class="nt"></script></span>
<span class="nt"></body></span>
<span class="nt"></html></span></pre>
<p>The <code>debug</code> function will be invoked twice. Each time the <a data-link-type="dfn" href="#concept-event">event</a>’s <code class="idl"><a data-link-type="idl" href="#dom-event-target">target</a></code> attribute value will be the <code>span</code> <a data-link-type="dfn" href="#concept-element">element</a>. The
first time <code class="idl"><a data-link-type="idl" href="#dom-event-currenttarget">currentTarget</a></code> attribute’s
value will be the <a data-link-type="dfn" href="#concept-document">document</a>, the second
time the <code>body</code> <a data-link-type="dfn" href="#concept-element">element</a>. <code class="idl"><a data-link-type="idl" href="#dom-event-eventphase">eventPhase</a></code> attribute’s value
switches from <code class="idl"><a data-link-type="idl" href="#dom-event-capturing_phase">CAPTURING_PHASE</a></code> to <code class="idl"><a data-link-type="idl" href="#dom-event-bubbling_phase">BUBBLING_PHASE</a></code>. If an <a data-link-type="dfn" href="#concept-event-listener">event listener</a> was registered for
the <code>span</code> <a data-link-type="dfn" href="#concept-element">element</a>, <code class="idl"><a data-link-type="idl" href="#dom-event-eventphase">eventPhase</a></code> attribute’s value
would have been <code class="idl"><a data-link-type="idl" href="#dom-event-at_target">AT_TARGET</a></code>.</p>
<h3 class="heading settled" data-level="3.2" id="interface-event"><span class="secno">3.2. </span><span class="content">Interface <code class="idl"><a data-link-type="idl" href="#event">Event</a></code></span><a class="self-link" href="#interface-event"></a></h3>
<pre class="idl def">[<dfn class="idl-code" data-dfn-for="Event" data-dfn-type="constructor" data-export="" data-lt="Event(type, eventInitDict)|Event(type)" id="dom-event-event">Constructor<a class="self-link" href="#dom-event-event"></a></dfn>(DOMString <dfn class="idl-code" data-dfn-for="Event/Event(type, eventInitDict)" data-dfn-type="argument" data-export="" id="dom-event-event-type-eventinitdict-type">type<a class="self-link" href="#dom-event-event-type-eventinitdict-type"></a></dfn>, optional <a data-link-type="idl-name" href="#dictdef-eventinit">EventInit</a> <dfn class="idl-code" data-dfn-for="Event/Event(type, eventInitDict)" data-dfn-type="argument" data-export="" id="dom-event-event-type-eventinitdict-eventinitdict">eventInitDict<a class="self-link" href="#dom-event-event-type-eventinitdict-eventinitdict"></a></dfn>),
Exposed=(Window,Worker)]
interface <dfn class="idl-code" data-dfn-type="interface" data-export="" id="event">Event<a class="self-link" href="#event"></a></dfn> {
readonly attribute DOMString <a class="idl-code" data-link-type="attribute" data-readonly="" data-type="DOMString " href="#dom-event-type">type</a>;
readonly attribute <a data-link-type="idl-name" href="#eventtarget">EventTarget</a>? <a class="idl-code" data-link-type="attribute" data-readonly="" data-type="EventTarget? " href="#dom-event-target">target</a>;
readonly attribute <a data-link-type="idl-name" href="#eventtarget">EventTarget</a>? <a class="idl-code" data-link-type="attribute" data-readonly="" data-type="EventTarget? " href="#dom-event-currenttarget">currentTarget</a>;
const unsigned short <a class="idl-code" data-link-type="const" href="#dom-event-none">NONE</a> = 0;
const unsigned short <a class="idl-code" data-link-type="const" href="#dom-event-capturing_phase">CAPTURING_PHASE</a> = 1;
const unsigned short <a class="idl-code" data-link-type="const" href="#dom-event-at_target">AT_TARGET</a> = 2;
const unsigned short <a class="idl-code" data-link-type="const" href="#dom-event-bubbling_phase">BUBBLING_PHASE</a> = 3;
readonly attribute unsigned short <a class="idl-code" data-link-type="attribute" data-readonly="" data-type="unsigned short " href="#dom-event-eventphase">eventPhase</a>;
void <a class="idl-code" data-link-type="method" href="#dom-event-stoppropagation">stopPropagation</a>();
void <a class="idl-code" data-link-type="method" href="#dom-event-stopimmediatepropagation">stopImmediatePropagation</a>();
readonly attribute boolean <a class="idl-code" data-link-type="attribute" data-readonly="" data-type="boolean " href="#dom-event-bubbles">bubbles</a>;
readonly attribute boolean <a class="idl-code" data-link-type="attribute" data-readonly="" data-type="boolean " href="#dom-event-cancelable">cancelable</a>;
void <a class="idl-code" data-link-type="method" href="#dom-event-preventdefault">preventDefault</a>();
readonly attribute boolean <a class="idl-code" data-link-type="attribute" data-readonly="" data-type="boolean " href="#dom-event-defaultprevented">defaultPrevented</a>;
[Unforgeable] readonly attribute boolean <a class="idl-code" data-link-type="attribute" data-readonly="" data-type="boolean " href="#dom-event-istrusted">isTrusted</a>;
readonly attribute <a data-link-type="idl-name" href="https://heycam.github.io/webidl/#common-domtimestamp">DOMTimeStamp</a> <a class="idl-code" data-link-type="attribute" data-readonly="" data-type="DOMTimeStamp " href="#dom-event-timestamp">timeStamp</a>;
void <a class="idl-code" data-link-type="method" href="#dom-event-initevent">initEvent</a>(DOMString <dfn class="idl-code" data-dfn-for="Event/initEvent(type, bubbles, cancelable)" data-dfn-type="argument" data-export="" id="dom-event-initevent-type-bubbles-cancelable-type">type<a class="self-link" href="#dom-event-initevent-type-bubbles-cancelable-type"></a></dfn>, boolean <dfn class="idl-code" data-dfn-for="Event/initEvent(type, bubbles, cancelable)" data-dfn-type="argument" data-export="" id="dom-event-initevent-type-bubbles-cancelable-bubbles">bubbles<a class="self-link" href="#dom-event-initevent-type-bubbles-cancelable-bubbles"></a></dfn>, boolean <dfn class="idl-code" data-dfn-for="Event/initEvent(type, bubbles, cancelable)" data-dfn-type="argument" data-export="" id="dom-event-initevent-type-bubbles-cancelable-cancelable">cancelable<a class="self-link" href="#dom-event-initevent-type-bubbles-cancelable-cancelable"></a></dfn>);
};
dictionary <dfn class="idl-code" data-dfn-type="dictionary" data-export="" id="dictdef-eventinit">EventInit<a class="self-link" href="#dictdef-eventinit"></a></dfn> {
boolean <dfn class="idl-code" data-default="false" data-dfn-for="EventInit" data-dfn-type="dict-member" data-export="" data-type="boolean " id="dom-eventinit-bubbles">bubbles<a class="self-link" href="#dom-eventinit-bubbles"></a></dfn> = false;
boolean <dfn class="idl-code" data-default="false" data-dfn-for="EventInit" data-dfn-type="dict-member" data-export="" data-type="boolean " id="dom-eventinit-cancelable">cancelable<a class="self-link" href="#dom-eventinit-cancelable"></a></dfn> = false;
};
</pre>
<p>An <dfn data-dfn-type="dfn" data-export="" id="concept-event">event<a class="self-link" href="#concept-event"></a></dfn> allows for signaling that
something has occurred, e.g. that an image has completed downloading. It is
represented by the <code class="idl"><a data-link-type="idl" href="#event">Event</a></code> interface or an interface that
inherits from the <code class="idl"><a data-link-type="idl" href="#event">Event</a></code> interface.</p>
<dl class="domintro">
<dt><code><var>event</var> = new <a class="idl-code" data-link-type="constructor" href="#dom-event-event">Event</a>(<var>type</var> [, <var>eventInitDict</var>])</code>
<dd>Returns a new <var>event</var> whose <code class="idl"><a data-link-type="idl" href="#dom-event-type">type</a></code> attribute value is set to <var>type</var>. The optional <code class="idl"><a class="idl-code" data-link-type="argument" href="#dom-event-event-type-eventinitdict-eventinitdict">eventInitDict</a></code> argument
allows for setting the <code class="idl"><a data-link-type="idl" href="#dom-event-bubbles">bubbles</a></code> and <code class="idl"><a data-link-type="idl" href="#dom-event-cancelable">cancelable</a></code> attributes via object
members of the same name.
<dt><code><var>event</var> . <code class="idl"><a data-link-type="idl" href="#dom-event-type">type</a></code></code>
<dd>Returns the type of <var>event</var>, e.g.
"<code>click</code>", "<code>hashchange</code>", or
"<code>submit</code>".
<dt><code><var>event</var> . <code class="idl"><a data-link-type="idl" href="#dom-event-target">target</a></code></code>
<dd>Returns the object to which <var>event</var> is <a data-link-type="dfn" href="#concept-event-dispatch">dispatched</a>.
<dt><code><var>event</var> . <code class="idl"><a data-link-type="idl" href="#dom-event-currenttarget">currentTarget</a></code></code>
<dd>Returns the object whose <a data-link-type="dfn" href="#concept-event-listener">event listener</a>’s <b>callback</b> is currently being
invoked.
<dt><code><var>event</var> . <code class="idl"><a data-link-type="idl" href="#dom-event-eventphase">eventPhase</a></code></code>
<dd>Returns the <a data-link-type="dfn" href="#concept-event">event</a>’s phase, which is one of <code class="idl"><a data-link-type="idl" href="#dom-event-none">NONE</a></code>, <code class="idl"><a data-link-type="idl" href="#dom-event-capturing_phase">CAPTURING_PHASE</a></code>, <code class="idl"><a data-link-type="idl" href="#dom-event-at_target">AT_TARGET</a></code>, and <code class="idl"><a data-link-type="idl" href="#dom-event-bubbling_phase">BUBBLING_PHASE</a></code>.
<dt><code><var>event</var> . <a class="idl-code" data-link-type="method" href="#dom-event-stoppropagation">stopPropagation</a>()</code>
<dd>When <a data-link-type="dfn" href="#concept-event-dispatch">dispatched</a> in a <a data-link-type="dfn" href="#concept-tree">tree</a>, invoking this method prevents <var>event</var> from reaching any objects other than the current object.
<dt><code><var>event</var> . <a class="idl-code" data-link-type="method" href="#dom-event-stopimmediatepropagation">stopImmediatePropagation</a>()</code>
<dd>Invoking this method prevents <var>event</var> from reaching
any registered <a data-link-type="dfn" href="#concept-event-listener">event listeners</a> after the current one finishes running and, when <a data-link-type="dfn" href="#concept-event-dispatch">dispatched</a> in a <a data-link-type="dfn" href="#concept-tree">tree</a>, also prevents <var>event</var> from reaching any
other objects.
<dt><code><var>event</var> . <code class="idl"><a data-link-type="idl" href="#dom-event-bubbles">bubbles</a></code></code>
<dd>Returns true or false depending on how <var>event</var> was initialized. True if <var>event</var> goes through its <code class="idl"><a data-link-type="idl" href="#dom-event-target">target</a></code> attribute value’s <a data-link-type="dfn" href="#concept-tree-ancestor">ancestors</a> in reverse <a data-link-type="dfn" href="#concept-tree-order">tree order</a>, and false otherwise.
<dt><code><var>event</var> . <code class="idl"><a data-link-type="idl" href="#dom-event-cancelable">cancelable</a></code></code>
<dd>Returns true or false depending on how <var>event</var> was initialized. Its return
value does not always carry meaning, but true can indicate that part of the operation
during which <var>event</var> was <a data-link-type="dfn" href="#concept-event-dispatch">dispatched</a>, can be canceled by invoking the <code class="idl"><a data-link-type="idl" href="#dom-event-preventdefault">preventDefault()</a></code> method.
<dt><code><var>event</var> . <a class="idl-code" data-link-type="method" href="#dom-event-preventdefault">preventDefault</a>()</code>
<dd>If invoked when the <code class="idl"><a data-link-type="idl" href="#dom-event-cancelable">cancelable</a></code> attribute value is true, and while executing a
listener for the <var>event</var> with <code class="idl"><a data-link-type="idl" href="#dom-eventlisteneroptions-passive">passive</a></code> set to false, signals to
the operation that caused <var>event</var> to be <a data-link-type="dfn" href="#concept-event-dispatch">dispatched</a> that it needs to be canceled.
<dt><code><var>event</var> . <code class="idl"><a data-link-type="idl" href="#dom-event-defaultprevented">defaultPrevented</a></code></code>
<dd>Returns true if <code class="idl"><a data-link-type="idl" href="#dom-event-preventdefault">preventDefault()</a></code> was invoked successfully to indicate cancellation,
and false otherwise.
<dt><code><var>event</var> . <code class="idl"><a data-link-type="idl" href="#dom-event-istrusted">isTrusted</a></code></code>
<dd>Returns true if <var>event</var> was <a data-link-type="dfn" href="#concept-event-dispatch">dispatched</a> by the user agent, and
false otherwise.
<dt><code><var>event</var> . <code class="idl"><a data-link-type="idl" href="#dom-event-timestamp">timeStamp</a></code></code>
<dd>Returns the creation time of <var>event</var> as the number of milliseconds that
passed since 00:00:00 UTC on 1 January 1970.
</dl>
<p>The <dfn class="idl-code" data-dfn-for="Event" data-dfn-type="attribute" data-export="" id="dom-event-type">type<a class="self-link" href="#dom-event-type"></a></dfn> attribute must
return the value it was initialized to. When an <a data-link-type="dfn" href="#concept-event">event</a> is created the attribute must be
initialized to the empty string.</p>
<p>The <dfn class="idl-code" data-dfn-for="Event" data-dfn-type="attribute" data-export="" id="dom-event-target">target<a class="self-link" href="#dom-event-target"></a></dfn> and <dfn class="idl-code" data-dfn-for="Event" data-dfn-type="attribute" data-export="" id="dom-event-currenttarget">currentTarget<a class="self-link" href="#dom-event-currenttarget"></a></dfn> attributes must return the values they were initialized to. When an <a data-link-type="dfn" href="#concept-event">event</a> is created the attributes must be
initialized to null.</p>
<p>The <dfn class="idl-code" data-dfn-for="Event" data-dfn-type="attribute" data-export="" id="dom-event-eventphase">eventPhase<a class="self-link" href="#dom-event-eventphase"></a></dfn> attribute must return the value it was initialized to, which must be one of
the following:</p>
<dl>
<dt><dfn class="idl-code" data-dfn-for="Event" data-dfn-type="const" data-export="" id="dom-event-none">NONE<a class="self-link" href="#dom-event-none"></a></dfn> (numeric value 0)
<dd><a data-link-type="dfn" href="#concept-event">Events</a> not currently <a data-link-type="dfn" href="#concept-event-dispatch">dispatched</a> are in this phase.
<dt><dfn class="idl-code" data-dfn-for="Event" data-dfn-type="const" data-export="" id="dom-event-capturing_phase">CAPTURING_PHASE<a class="self-link" href="#dom-event-capturing_phase"></a></dfn> (numeric value 1)
<dd>When an <a data-link-type="dfn" href="#concept-event">event</a> is <a data-link-type="dfn" href="#concept-event-dispatch">dispatched</a> to an object that <a data-link-type="dfn" href="#concept-tree-participate">participates</a> in a <a data-link-type="dfn" href="#concept-tree">tree</a> it will be in this phase before it
reaches its <code class="idl"><a data-link-type="idl" href="#dom-event-target">target</a></code> attribute value.
<dt><dfn class="idl-code" data-dfn-for="Event" data-dfn-type="const" data-export="" id="dom-event-at_target">AT_TARGET<a class="self-link" href="#dom-event-at_target"></a></dfn> (numeric value 2)
<dd>When an <a data-link-type="dfn" href="#concept-event">event</a> is <a data-link-type="dfn" href="#concept-event-dispatch">dispatched</a> it will be in this
phase on its <code class="idl"><a data-link-type="idl" href="#dom-event-target">target</a></code> attribute value.
<dt><dfn class="idl-code" data-dfn-for="Event" data-dfn-type="const" data-export="" id="dom-event-bubbling_phase">BUBBLING_PHASE<a class="self-link" href="#dom-event-bubbling_phase"></a></dfn> (numeric value 3)
<dd>When an <a data-link-type="dfn" href="#concept-event">event</a> is <a data-link-type="dfn" href="#concept-event-dispatch">dispatched</a> to an object that <a data-link-type="dfn" href="#concept-tree-participate">participates</a> in a <a data-link-type="dfn" href="#concept-tree">tree</a> it will be in this phase after it
reaches its <code class="idl"><a data-link-type="idl" href="#dom-event-target">target</a></code> attribute value.
</dl>
Initially the attribute must be initialized to <code class="idl"><a data-link-type="idl" href="#dom-event-none">NONE</a></code>.
<hr>
<p>Each <a data-link-type="dfn" href="#concept-event">event</a> has the following associated
flags that are all initially unset:</p>
<ul>
<li><dfn data-dfn-for="Event" data-dfn-type="dfn" data-export="" id="stop-propagation-flag">stop propagation flag<a class="self-link" href="#stop-propagation-flag"></a></dfn>
<li><dfn data-dfn-for="Event" data-dfn-type="dfn" data-export="" id="stop-immediate-propagation-flag">stop immediate propagation flag<a class="self-link" href="#stop-immediate-propagation-flag"></a></dfn>
<li><dfn data-dfn-for="Event" data-dfn-type="dfn" data-export="" id="canceled-flag">canceled flag<a class="self-link" href="#canceled-flag"></a></dfn>
<li><dfn data-dfn-for="Event" data-dfn-type="dfn" data-export="" id="initialized-flag">initialized flag<a class="self-link" href="#initialized-flag"></a></dfn>
<li><dfn data-dfn-for="Event" data-dfn-type="dfn" data-export="" id="dispatch-flag">dispatch flag<a class="self-link" href="#dispatch-flag"></a></dfn>
<li><dfn data-dfn-for="Event" data-dfn-type="dfn" data-export="" id="in-passive-listener-flag">in passive listener flag<a class="self-link" href="#in-passive-listener-flag"></a></dfn>
</ul>
<p>The <dfn class="idl-code" data-dfn-for="Event" data-dfn-type="method" data-export="" id="dom-event-stoppropagation">stopPropagation()<a class="self-link" href="#dom-event-stoppropagation"></a></dfn> method must set the <a data-link-type="dfn" href="#stop-propagation-flag">stop propagation flag</a>.</p>
<p>The <dfn class="idl-code" data-dfn-for="Event" data-dfn-type="method" data-export="" id="dom-event-stopimmediatepropagation">stopImmediatePropagation()<a class="self-link" href="#dom-event-stopimmediatepropagation"></a></dfn> method must set both the <a data-link-type="dfn" href="#stop-propagation-flag">stop propagation flag</a> and <a data-link-type="dfn" href="#stop-immediate-propagation-flag">stop immediate propagation flag</a>.</p>
<p>The <dfn class="idl-code" data-dfn-for="Event" data-dfn-type="attribute" data-export="" id="dom-event-bubbles">bubbles<a class="self-link" href="#dom-event-bubbles"></a></dfn> and <dfn class="idl-code" data-dfn-for="Event" data-dfn-type="attribute" data-export="" id="dom-event-cancelable">cancelable<a class="self-link" href="#dom-event-cancelable"></a></dfn> attributes
must return the values they were initialized to.</p>
<p>The <dfn class="idl-code" data-dfn-for="Event" data-dfn-type="method" data-export="" id="dom-event-preventdefault"><code>preventDefault()</code><a class="self-link" href="#dom-event-preventdefault"></a></dfn> method, when invoked, must set the <a data-link-type="dfn" href="#canceled-flag">canceled flag</a> if the <code class="idl"><a data-link-type="idl" href="#dom-event-cancelable">cancelable</a></code> attribute value is true and the <a data-link-type="dfn" href="#in-passive-listener-flag">in passive listener flag</a> is unset.</p>
<p class="note no-backref" role="note">This means there are scenarios where invoking <code class="idl"><a data-link-type="idl" href="#dom-event-preventdefault">preventDefault()</a></code> has no
effect. User agents are encouraged to log the precise cause in a developer console, to aid
debugging. </p>
<p>The <dfn class="idl-code" data-dfn-for="Event" data-dfn-type="attribute" data-export="" id="dom-event-defaultprevented">defaultPrevented<a class="self-link" href="#dom-event-defaultprevented"></a></dfn> attribute must return true if the <a data-link-type="dfn" href="#canceled-flag">canceled flag</a> is set and
false otherwise.</p>
<hr>
<p>The <dfn class="idl-code" data-dfn-for="Event" data-dfn-type="attribute" data-export="" id="dom-event-istrusted">isTrusted<a class="self-link" href="#dom-event-istrusted"></a></dfn> attribute
must return the value it was initialized to. When an <a data-link-type="dfn" href="#concept-event">event</a> is created the attribute must be
initialized to false.</p>
<p>The <dfn class="idl-code" data-dfn-for="Event" data-dfn-type="attribute" data-export="" id="dom-event-timestamp">timeStamp<a class="self-link" href="#dom-event-timestamp"></a></dfn> attribute
must return the value it was initialized to. When an <a data-link-type="dfn" href="#concept-event">event</a> is created the attribute must be
initialized to the number of milliseconds that have passed since
00:00:00 UTC on 1 January 1970, ignoring leap seconds.</p>
<hr>
<p>To <dfn data-dfn-for="Event" data-dfn-type="dfn" data-export="" id="concept-event-initialize">initialize<a class="self-link" href="#concept-event-initialize"></a></dfn> an <var>event</var>, with <var>type</var>, <var>bubbles</var>, and <var>cancelable</var>, run these steps:</p>
<ol>
<li>Set the <a data-link-type="dfn" href="#initialized-flag">initialized flag</a>.
<li>Unset the <a data-link-type="dfn" href="#stop-propagation-flag">stop propagation flag</a>, <a data-link-type="dfn" href="#stop-immediate-propagation-flag">stop immediate propagation flag</a>, and <a data-link-type="dfn" href="#canceled-flag">canceled flag</a>.
<li>Set the <code class="idl"><a data-link-type="idl" href="#dom-event-istrusted">isTrusted</a></code> attribute
to false.
<li>Set the <code class="idl"><a data-link-type="idl" href="#dom-event-target">target</a></code> attribute to
null.
<li>Set the <code class="idl"><a data-link-type="idl" href="#dom-event-type">type</a></code> attribute to <var>type</var>.
<li>Set the <code class="idl"><a data-link-type="idl" href="#dom-event-bubbles">bubbles</a></code> attribute to <var>bubbles</var>.
<li>Set the <code class="idl"><a data-link-type="idl" href="#dom-event-cancelable">cancelable</a></code> attribute
to <var>cancelable</var>.
</ol>
<p>The <dfn class="idl-code" data-dfn-for="Event" data-dfn-type="method" data-export="" id="dom-event-initevent">initEvent(<var>type</var>, <var>bubbles</var>, <var>cancelable</var>)<a class="self-link" href="#dom-event-initevent"></a></dfn> method, when invoked, must run these steps:</p>
<ol>
<li>If <a data-link-type="dfn" href="#context-object">context object</a>’s <a data-link-type="dfn" href="#dispatch-flag">dispatch flag</a> is set, terminate
these steps.
<li><a data-link-type="dfn" href="#concept-event-initialize">Initialize</a> the <a data-link-type="dfn" href="#context-object">context object</a> with <var>type</var>, <var>bubbles</var>, and <var>cancelable</var>.
</ol>
<p class="note no-backref" role="note">As <a data-link-type="dfn" href="#concept-event">events</a> have constructors <code class="idl"><a data-link-type="idl" href="#dom-event-initevent">initEvent()</a></code> is superfluous. However,
it has to be supported for legacy content. </p>
<h3 class="heading settled" data-level="3.3" id="interface-customevent"><span class="secno">3.3. </span><span class="content">Interface <code class="idl"><a data-link-type="idl" href="#customevent">CustomEvent</a></code></span><a class="self-link" href="#interface-customevent"></a></h3>
<pre class="idl def">[<dfn class="idl-code" data-dfn-for="CustomEvent" data-dfn-type="constructor" data-export="" data-lt="CustomEvent(type, eventInitDict)|CustomEvent(type)" id="dom-customevent-customevent">Constructor<a class="self-link" href="#dom-customevent-customevent"></a></dfn>(DOMString <dfn class="idl-code" data-dfn-for="CustomEvent/CustomEvent(type, eventInitDict)" data-dfn-type="argument" data-export="" id="dom-customevent-customevent-type-eventinitdict-type">type<a class="self-link" href="#dom-customevent-customevent-type-eventinitdict-type"></a></dfn>, optional <a data-link-type="idl-name" href="#dictdef-customeventinit">CustomEventInit</a> <dfn class="idl-code" data-dfn-for="CustomEvent/CustomEvent(type, eventInitDict)" data-dfn-type="argument" data-export="" id="dom-customevent-customevent-type-eventinitdict-eventinitdict">eventInitDict<a class="self-link" href="#dom-customevent-customevent-type-eventinitdict-eventinitdict"></a></dfn>),
Exposed=(Window,Worker)]
interface <dfn class="idl-code" data-dfn-type="interface" data-export="" id="customevent">CustomEvent<a class="self-link" href="#customevent"></a></dfn> : <a data-link-type="idl-name" href="#event">Event</a> {
readonly attribute any <a class="idl-code" data-link-type="attribute" data-readonly="" data-type="any " href="#dom-customevent-detail">detail</a>;
void <a class="idl-code" data-link-type="method" href="#dom-customevent-initcustomevent">initCustomEvent</a>(DOMString <dfn class="idl-code" data-dfn-for="CustomEvent/initCustomEvent(type, bubbles, cancelable, detail)" data-dfn-type="argument" data-export="" id="dom-customevent-initcustomevent-type-bubbles-cancelable-detail-type">type<a class="self-link" href="#dom-customevent-initcustomevent-type-bubbles-cancelable-detail-type"></a></dfn>, boolean <dfn class="idl-code" data-dfn-for="CustomEvent/initCustomEvent(type, bubbles, cancelable, detail)" data-dfn-type="argument" data-export="" id="dom-customevent-initcustomevent-type-bubbles-cancelable-detail-bubbles">bubbles<a class="self-link" href="#dom-customevent-initcustomevent-type-bubbles-cancelable-detail-bubbles"></a></dfn>, boolean <dfn class="idl-code" data-dfn-for="CustomEvent/initCustomEvent(type, bubbles, cancelable, detail)" data-dfn-type="argument" data-export="" id="dom-customevent-initcustomevent-type-bubbles-cancelable-detail-cancelable">cancelable<a class="self-link" href="#dom-customevent-initcustomevent-type-bubbles-cancelable-detail-cancelable"></a></dfn>, any <dfn class="idl-code" data-dfn-for="CustomEvent/initCustomEvent(type, bubbles, cancelable, detail)" data-dfn-type="argument" data-export="" id="dom-customevent-initcustomevent-type-bubbles-cancelable-detail-detail">detail<a class="self-link" href="#dom-customevent-initcustomevent-type-bubbles-cancelable-detail-detail"></a></dfn>);
};
dictionary <dfn class="idl-code" data-dfn-type="dictionary" data-export="" id="dictdef-customeventinit">CustomEventInit<a class="self-link" href="#dictdef-customeventinit"></a></dfn> : <a data-link-type="idl-name" href="#dictdef-eventinit">EventInit</a> {
any <dfn class="idl-code" data-default="null" data-dfn-for="CustomEventInit" data-dfn-type="dict-member" data-export="" data-type="any " id="dom-customeventinit-detail">detail<a class="self-link" href="#dom-customeventinit-detail"></a></dfn> = null;
};
</pre>
<p><a data-link-type="dfn" href="#concept-event">Events</a> using the <code class="idl"><a data-link-type="idl" href="#customevent">CustomEvent</a></code> interface can be used to carry custom data.</p>
<dl class="domintro">
<dt><code><var>event</var> = new <a class="idl-code" data-link-type="constructor" href="#dom-customevent-customevent">CustomEvent</a>(<var>type</var> [, <var>eventInitDict</var>])</code>
<dd>Works analogously to the constructor for <code class="idl"><a data-link-type="idl" href="#event">Event</a></code> except
that the optional <var>eventInitDict</var> argument now
allows for setting the <code class="idl"><a data-link-type="idl" href="#dom-customevent-detail">detail</a></code> attribute
too.
<dt><code><var>event</var> . <code class="idl"><a data-link-type="idl" href="#dom-customevent-detail">detail</a></code></code>
<dd>Returns any custom data <var>event</var> was created with.
Typically used for synthetic events.
</dl>
<p>The <dfn class="idl-code" data-dfn-for="CustomEvent" data-dfn-type="attribute" data-export="" id="dom-customevent-detail">detail<a class="self-link" href="#dom-customevent-detail"></a></dfn> attribute
must return the value it was initialized to.</p>
<p>The <dfn class="idl-code" data-dfn-for="CustomEvent" data-dfn-type="method" data-export="" id="dom-customevent-initcustomevent">initCustomEvent(<var>type</var>, <var>bubbles</var>, <var>cancelable</var>, <var>detail</var>)<a class="self-link" href="#dom-customevent-initcustomevent"></a></dfn> method must, when invoked, run these steps:</p>
<ol>
<li>If <a data-link-type="dfn" href="#context-object">context object</a>’s <a data-link-type="dfn" href="#dispatch-flag">dispatch flag</a> is set, terminate
these steps.
<li><a data-link-type="dfn" href="#concept-event-initialize">Initialize</a> the <a data-link-type="dfn" href="#context-object">context object</a> with <var>type</var>, <var>bubbles</var>, and <var>cancelable</var>.
<li>Set <a data-link-type="dfn" href="#context-object">context object</a>’s <code class="idl"><a data-link-type="idl" href="#dom-customevent-detail">detail</a></code> attribute to <var>detail</var>.
</ol>
<h3 class="heading settled" data-level="3.4" id="constructing-events"><span class="secno">3.4. </span><span class="content">Constructing events</span><a class="self-link" href="#constructing-events"></a></h3>
<p>When a <dfn data-dfn-for="Event" data-dfn-type="dfn" data-export="" id="concept-event-constructor">constructor<a class="self-link" href="#concept-event-constructor"></a></dfn> of the <code class="idl"><a data-link-type="idl" href="#event">Event</a></code> interface, or of an interface that inherits from the <code class="idl"><a data-link-type="idl" href="#event">Event</a></code> interface, is
invoked, these steps must be run:</p>
<ol>
<li>
<p>Create an <a data-link-type="dfn" href="#concept-event">event</a> that uses the interface the constructor was invoked upon. </p>
<li>
<p>Set its <a data-link-type="dfn" href="#initialized-flag">initialized flag</a>. </p>
<li>
<p>Initialize the <code class="idl"><a data-link-type="idl" href="#dom-event-type">type</a></code> attribute to the <var>type</var> argument. </p>
<li>
<p>If there is an <var>eventInitDict</var> argument, then for each <a data-link-type="dfn" href="https://heycam.github.io/webidl/#dfn-dictionary-member">dictionary member</a> present, find the attribute on <a data-link-type="dfn" href="#concept-event">event</a> whose <a data-link-type="dfn" href="https://heycam.github.io/webidl/#dfn-identifier">identifier</a> matches the key of the <a data-link-type="dfn" href="https://heycam.github.io/webidl/#dfn-dictionary-member">dictionary member</a> and then set the
attribute to the value of that <a data-link-type="dfn" href="https://heycam.github.io/webidl/#dfn-dictionary-member">dictionary member</a>. </p>
<li>
<p>Return the <a data-link-type="dfn" href="#concept-event">event</a>. </p>
</ol>
<h3 class="heading settled" data-level="3.5" id="defining-event-interfaces"><span class="secno">3.5. </span><span class="content">Defining event interfaces</span><a class="self-link" href="#defining-event-interfaces"></a></h3>
<p>In general, when defining a new interface that inherits from <code class="idl"><a data-link-type="idl" href="#event">Event</a></code> please always ask
feedback from the <a href="https://whatwg.org/">WHATWG</a> or the <a href="https://www.w3.org/2008/webapps/">W3C WebApps WG</a> community.</p>
<p>The <code class="idl"><a data-link-type="idl" href="#customevent">CustomEvent</a></code> interface can be used as starting point.
However, do not introduce any <code>init<var>*</var>Event()</code> methods as they are redundant with constructors. Interfaces that inherit
from the <code class="idl"><a data-link-type="idl" href="#event">Event</a></code> interface that have such a method only have it
for historical reasons.</p>
<h3 class="heading settled" data-level="3.6" id="interface-eventtarget"><span class="secno">3.6. </span><span class="content">Interface <code class="idl"><a data-link-type="idl" href="#eventtarget">EventTarget</a></code></span><a class="self-link" href="#interface-eventtarget"></a></h3>
<pre class="idl def">[Exposed=(Window,Worker)]
interface <dfn class="idl-code" data-dfn-type="interface" data-export="" id="eventtarget">EventTarget<a class="self-link" href="#eventtarget"></a></dfn> {
void <a class="idl-code" data-link-type="method" href="#dom-eventtarget-addeventlistener">addEventListener</a>(DOMString <dfn class="idl-code" data-dfn-for="EventTarget/addEventListener(type, callback, options), EventTarget/addEventListener(type, callback)" data-dfn-type="argument" data-export="" id="dom-eventtarget-addeventlistener-type-callback-options-type">type<a class="self-link" href="#dom-eventtarget-addeventlistener-type-callback-options-type"></a></dfn>, <a data-link-type="idl-name" href="#callbackdef-eventlistener">EventListener</a>? callback, optional (<a data-link-type="idl-name" href="#dictdef-eventlisteneroptions">EventListenerOptions</a> or boolean) <dfn class="idl-code" data-dfn-for="EventTarget/addEventListener(type, callback, options), EventTarget/addEventListener(type, callback)" data-dfn-type="argument" data-export="" id="dom-eventtarget-addeventlistener-type-callback-options-options">options<a class="self-link" href="#dom-eventtarget-addeventlistener-type-callback-options-options"></a></dfn>);
void <a class="idl-code" data-link-type="method" href="#dom-eventtarget-removeeventlistener">removeEventListener</a>(DOMString <dfn class="idl-code" data-dfn-for="EventTarget/removeEventListener(type, callback, options), EventTarget/removeEventListener(type, callback)" data-dfn-type="argument" data-export="" id="dom-eventtarget-removeeventlistener-type-callback-options-type">type<a class="self-link" href="#dom-eventtarget-removeeventlistener-type-callback-options-type"></a></dfn>, <a data-link-type="idl-name" href="#callbackdef-eventlistener">EventListener</a>? callback, optional (<a data-link-type="idl-name" href="#dictdef-eventlisteneroptions">EventListenerOptions</a> or boolean) <dfn class="idl-code" data-dfn-for="EventTarget/removeEventListener(type, callback, options), EventTarget/removeEventListener(type, callback)" data-dfn-type="argument" data-export="" id="dom-eventtarget-removeeventlistener-type-callback-options-options">options<a class="self-link" href="#dom-eventtarget-removeeventlistener-type-callback-options-options"></a></dfn>);
boolean <a class="idl-code" data-link-type="method" href="#dom-eventtarget-dispatchevent">dispatchEvent</a>(<a data-link-type="idl-name" href="#event">Event</a> <dfn class="idl-code" data-dfn-for="EventTarget/dispatchEvent(event)" data-dfn-type="argument" data-export="" id="dom-eventtarget-dispatchevent-event-event">event<a class="self-link" href="#dom-eventtarget-dispatchevent-event-event"></a></dfn>);
};
callback interface <dfn class="idl-code" data-dfn-type="callback" data-export="" id="callbackdef-eventlistener">EventListener<a class="self-link" href="#callbackdef-eventlistener"></a></dfn> {
void <dfn class="idl-code" data-dfn-for="EventListener" data-dfn-type="method" data-export="" data-lt="handleEvent(event)" id="dom-eventlistener-handleevent">handleEvent<a class="self-link" href="#dom-eventlistener-handleevent"></a></dfn>(<a data-link-type="idl-name" href="#event">Event</a> <dfn class="idl-code" data-dfn-for="EventListener/handleEvent(event)" data-dfn-type="argument" data-export="" id="dom-eventlistener-handleevent-event-event">event<a class="self-link" href="#dom-eventlistener-handleevent-event-event"></a></dfn>);
};
dictionary <dfn class="idl-code" data-dfn-type="dictionary" data-export="" id="dictdef-eventlisteneroptions">EventListenerOptions<a class="self-link" href="#dictdef-eventlisteneroptions"></a></dfn> {
boolean <dfn class="idl-code" data-dfn-for="EventListenerOptions" data-dfn-type="dict-member" data-export="" data-type="boolean " id="dom-eventlisteneroptions-capture">capture<a class="self-link" href="#dom-eventlisteneroptions-capture"></a></dfn>;
boolean <dfn class="idl-code" data-dfn-for="EventListenerOptions" data-dfn-type="dict-member" data-export="" data-type="boolean " id="dom-eventlisteneroptions-passive">passive<a class="self-link" href="#dom-eventlisteneroptions-passive"></a></dfn>;
};
</pre>
<p>The <code class="idl"><a data-link-type="idl" href="#eventtarget">EventTarget</a></code> object represents the target to which an <a data-link-type="dfn" href="#concept-event">event</a> is <a data-link-type="dfn" href="#concept-event-dispatch">dispatched</a> when something has occurred. </p>
<p>Each <code class="idl"><a data-link-type="idl" href="#eventtarget">EventTarget</a></code> object has an associated list of <a data-link-type="dfn" href="#concept-event-listener">event listeners</a>. </p>
<p>An <dfn data-dfn-type="dfn" data-export="" id="concept-event-listener">event listener<a class="self-link" href="#concept-event-listener"></a></dfn> can be used to observe a specific <a data-link-type="dfn" href="#concept-event">event</a>. </p>
<p>An <a data-link-type="dfn" href="#concept-event-listener">event listener</a> consists of these fields:</p>
<ul class="brief">
<li><b>type</b> (a string)
<li><b>callback</b> (an <code class="idl"><a data-link-type="idl" href="#callbackdef-eventlistener">EventListener</a></code>
<li><b>capture</b> (a boolean, initially false)
<li><b>passive</b> (a boolean, initially false)
<li><b>removed</b> (a boolean for bookkeeping purposes, initially false)
</ul>
<p class="note no-backref" role="note">Although <b>callback</b> is an <code class="idl"><a data-link-type="idl" href="#callbackdef-eventlistener">EventListener</a></code>, as can be seen from the
fields above, an <a data-link-type="dfn" href="#concept-event-listener">event listener</a> is a broader concept. </p>
<p>Each <code class="idl"><a data-link-type="idl" href="#eventtarget">EventTarget</a></code> object also has an associated <dfn data-dfn-type="dfn" data-export="" id="get-the-parent">get the parent<a class="self-link" href="#get-the-parent"></a></dfn> algorithm,
which takes an <a data-link-type="dfn" href="#concept-event">event</a> <var>event</var>, and returns an <code class="idl"><a data-link-type="idl" href="#eventtarget">EventTarget</a></code> object. Unless
specified otherwise it returns null. </p>
<p class="note no-backref" role="note"><a data-link-type="dfn" href="#concept-node">Nodes</a> and <a data-link-type="dfn" href="#concept-document">documents</a> override the <span>get the parent</span> algorithm. </p>
<dl class="domintro">
<dt><code><var>target</var> . <a class="idl-code" data-link-type="method" href="#dom-eventtarget-addeventlistener">addEventListener</a>(<var>type</var>, <var>callback</var> [, <var>options</var>])</code>
<dd>
Appends an <a data-link-type="dfn" href="#concept-event-listener">event listener</a> for <a data-link-type="dfn" href="#concept-event">events</a> whose <code class="idl"><a data-link-type="idl" href="#dom-event-type">type</a></code> attribute value
is <var>type</var>. The <var>callback</var> argument sets the <b>callback</b> that will
be invoked when the <a data-link-type="dfn" href="#concept-event">event</a> is <a data-link-type="dfn" href="#concept-event-dispatch">dispatched</a>.
<p>The <var>options</var> argument sets listener-specific options. For compatibility this can be just
a boolean, in which case the method behaves exactly as if the value was specified as <var>options</var>’ <code>capture</code> member.</p>
<p>When set to true, <var>options</var>’ <code>capture</code> member prevents <b>callback</b> from
being invoked when the <a data-link-type="dfn" href="#concept-event">event</a>’s <code class="idl"><a data-link-type="idl" href="#dom-event-eventphase">eventPhase</a></code> attribute value is <code class="idl"><a data-link-type="idl" href="#dom-event-bubbling_phase">BUBBLING_PHASE</a></code>. When false (or not present), <b>callback</b> will not be invoked when <a data-link-type="dfn" href="#concept-event">event</a>’s <code class="idl"><a data-link-type="idl" href="#dom-event-eventphase">eventPhase</a></code> attribute value is <code class="idl"><a data-link-type="idl" href="#dom-event-capturing_phase">CAPTURING_PHASE</a></code>. Either way, <b>callback</b> will be invoked if <a data-link-type="dfn" href="#concept-event">event</a>’s <code class="idl"><a data-link-type="idl" href="#dom-event-eventphase">eventPhase</a></code> attribute value is <code class="idl"><a data-link-type="idl" href="#dom-event-at_target">AT_TARGET</a></code>.</p>
<p>When set to true, <var>options</var>’ <code>passive</code> member indicates that the <b>callback</b> will not cancel the event by invoking <code class="idl"><a data-link-type="idl" href="#dom-event-preventdefault">preventDefault()</a></code>. This is used to enable
performance optimizations described in <a href="#observing-event-listeners">§3.7 Observing event listeners</a>.</p>
<p>The <a data-link-type="dfn" href="#concept-event-listener">event listener</a> is appended to <var>target</var>’s list of <a data-link-type="dfn" href="#concept-event-listener">event listeners</a> and is
not appended if it is a duplicate, i.e., having the same <b>type</b>, <b>callback</b>, <b>capture</b> and <b>passive</b> values.</p>
<dt><code><var>target</var> . <a class="idl-code" data-link-type="method" href="#dom-eventtarget-removeeventlistener">removeEventListener</a>(<var>type</var>, <var>callback</var> [, <var>options</var>])</code>
<dd>Remove the <a data-link-type="dfn" href="#concept-event-listener">event listener</a> in <var>target</var>’s list of <a data-link-type="dfn" href="#concept-event-listener">event listeners</a> with the same <var>type</var>, <var>callback</var>, and <var>options</var>.
<dt><code><var>target</var> . <a class="idl-code" data-link-type="method" href="#dom-eventtarget-dispatchevent">dispatchEvent</a>(<var>event</var>)</code>
<dd><a data-link-type="dfn" href="#concept-event-dispatch">Dispatches</a> a synthetic event <var>event</var> to <var>target</var> and returns
true if either <var>event</var>’s <code class="idl"><a data-link-type="idl" href="#dom-event-cancelable">cancelable</a></code> attribute value is false or its <code class="idl"><a data-link-type="idl" href="#dom-event-preventdefault">preventDefault()</a></code> method was not invoked, and false otherwise.
</dl>
<p>To <dfn data-dfn-for="Event" data-dfn-type="dfn" data-export="" id="concept-flatten-options">flatten<a class="self-link" href="#concept-flatten-options"></a></dfn> <var>options</var> run these steps: </p>
<ol>
<li>
<p>Let <var>capture</var> and <var>passive</var> be false. </p>
<li>
<p>If <var>options</var> is a boolean, set <var>capture</var> to <var>options</var>. </p>
<li>
<p>If <var>options</var> is a dictionary and <code><code class="idl"><a data-link-type="idl" href="#dom-eventlisteneroptions-capture">capture</a></code></code> is
present in <var>options</var> with value true, then set <var>capture</var> to true. </p>
<li>
<p>If <var>options</var> is a dictionary and <code><code class="idl"><a data-link-type="idl" href="#dom-eventlisteneroptions-passive">passive</a></code></code> is
present in <var>options</var> with value true, then set <var>passive</var> to true. </p>
<li>
<p>Return <var>capture</var> and <var>passive</var>. </p>
</ol>
<p>The <dfn class="idl-code" data-dfn-for="EventTarget" data-dfn-type="method" data-export="" data-lt="addEventListener(type, callback, options)|addEventListener(type, callback)" id="dom-eventtarget-addeventlistener"><code>addEventListener(<var>type</var>, <var>callback</var>, <var>options</var>)</code><a class="self-link" href="#dom-eventtarget-addeventlistener"></a></dfn> method, when invoked, must run these steps: </p>
<ol>
<li>
<p>If the <a data-link-type="dfn" href="#context-object">context object</a>’s global object is a <code class="idl"><a data-link-type="idl" href="https://slightlyoff.github.io/ServiceWorker/spec/service_worker/#service-worker-global-scope-interface">ServiceWorkerGlobalScope</a></code> object and its
associated <a data-link-type="dfn" href="https://slightlyoff.github.io/ServiceWorker/spec/service_worker/#dfn-service-worker">service worker</a>’s <a data-link-type="dfn" href="https://slightlyoff.github.io/ServiceWorker/spec/service_worker/#dfn-script-resource">script resource</a>’s <a data-link-type="dfn" href="https://slightlyoff.github.io/ServiceWorker/spec/service_worker/#dfn-has-ever-been-evaluated-flag">has ever been evaluated flag</a> is
set, <a data-link-type="dfn" href="https://heycam.github.io/webidl/#dfn-throw">throw</a> a <code>TypeError</code>. <a data-link-type="biblio" href="#biblio-service-workers">[SERVICE-WORKERS]</a> </p>
<p class="note no-backref" role="note">To optimize storing the event types allowed for the service worker and
to avoid non-deterministic changes to the event listeners, invocation of the method is allowed
only during the very first evaluation of the service worker script. </p>
<li>
<p>If <var>callback</var> is null, terminate these steps. </p>
<li>
<p>Let <var>capture</var> and <var>passive</var> be the result of <a data-link-type="dfn" href="#concept-flatten-options">flattening</a> <var>options</var>. </p>
<li>
<p>Append an <a data-link-type="dfn" href="#concept-event-listener">event listener</a> to the associated list of <a data-link-type="dfn" href="#concept-event-listener">event listeners</a> with <b>type</b> set to <var>type</var>, <b>callback</b> set to <var>callback</var>, <b>capture</b> set to <var>capture</var>, and <b>passive</b> set to <var>passive</var> unless there already is an <a data-link-type="dfn" href="#concept-event-listener">event listener</a> in that list with the same <b>type</b>, <b>callback</b>, <b>capture</b>, and <b>passive</b>. </p>
</ol>
<p>The <dfn class="idl-code" data-dfn-for="EventTarget" data-dfn-type="method" data-export="" data-lt="removeEventListener(type, callback, options)|removeEventListener(type, callback)" id="dom-eventtarget-removeeventlistener"><code>removeEventListener(<var>type</var>, <var>callback</var>, <var>options</var>)</code><a class="self-link" href="#dom-eventtarget-removeeventlistener"></a></dfn> method, when invoked, must, run these steps </p>
<ol>
<li>
<p>If the <a data-link-type="dfn" href="#context-object">context object</a>’s global object is a <code class="idl"><a data-link-type="idl" href="https://slightlyoff.github.io/ServiceWorker/spec/service_worker/#service-worker-global-scope-interface">ServiceWorkerGlobalScope</a></code> object and
its associated <a data-link-type="dfn" href="https://slightlyoff.github.io/ServiceWorker/spec/service_worker/#dfn-service-worker">service worker</a>’s <a data-link-type="dfn" href="https://slightlyoff.github.io/ServiceWorker/spec/service_worker/#dfn-script-resource">script resource</a>’s <a data-link-type="dfn" href="https://slightlyoff.github.io/ServiceWorker/spec/service_worker/#dfn-has-ever-been-evaluated-flag">has ever been evaluated flag</a> is set, <a data-link-type="dfn" href="https://heycam.github.io/webidl/#dfn-throw">throw</a> a <code>TypeError</code>. <a data-link-type="biblio" href="#biblio-service-workers">[SERVICE-WORKERS]</a> </p>
<li>
<p>Let <var>capture</var> and <var>passive</var> be the result of <a data-link-type="dfn" href="#concept-flatten-options">flattening</a> <var>options</var>. </p>
<li>
<p>If there is an <a data-link-type="dfn" href="#concept-event-listener">event listener</a> in the associated list of <a data-link-type="dfn" href="#concept-event-listener">event listeners</a> whose <b>type</b> is <var>type</var>, <b>callback</b> is <var>callback</var>, <b>capture</b> is <var>capture</var>, and <b>passive</b> is <var>passive</var> then set that <a data-link-type="dfn" href="#concept-event-listener">event listener</a>’s <b>removed</b> to true and remove it from the associated list of <a data-link-type="dfn" href="#concept-event-listener">event listeners</a>. </p>
</ol>
<p>The <dfn class="idl-code" data-dfn-for="EventTarget" data-dfn-type="method" data-export="" id="dom-eventtarget-dispatchevent"><code>dispatchEvent(<var>event</var>)</code><a class="self-link" href="#dom-eventtarget-dispatchevent"></a></dfn> method, when
invoked, must run these steps: </p>
<ol>
<li>
<p>If <var>event</var>’s <a data-link-type="dfn" href="#dispatch-flag">dispatch flag</a> is set, or if its <a data-link-type="dfn" href="#initialized-flag">initialized flag</a> is not
set, <a data-link-type="dfn" href="https://heycam.github.io/webidl/#dfn-throw">throw</a> an <code class="idl"><a data-link-type="idl" href="https://heycam.github.io/webidl/#invalidstateerror">InvalidStateError</a></code> exception. </p>
<li>
<p>Initialize <var>event</var>’s <code class="idl"><a data-link-type="idl" href="#dom-event-istrusted">isTrusted</a></code> attribute to false. </p>
<li>
<p>Return the result of <a data-link-type="dfn" href="#concept-event-dispatch">dispatching</a> <var>event</var> to the <a data-link-type="dfn" href="#context-object">context object</a>. </p>
</ol>
<h3 class="heading settled" data-level="3.7" id="observing-event-listeners"><span class="secno">3.7. </span><span class="content">Observing event listeners</span><a class="self-link" href="#observing-event-listeners"></a></h3>
<p>In general, developers do not expect the presence of an <a data-link-type="dfn" href="#concept-event-listener">event listener</a> to be observable.
The impact of an <a data-link-type="dfn" href="#concept-event-listener">event listener</a> is determined by its <b>callback</b>. That is, a developer
adding a no-op <a data-link-type="dfn" href="#concept-event-listener">event listener</a> would not expect it to have any side effects. </p>
<p>Unfortunately, some event APIs have been designed such that implementing them efficiently
requires observing <a data-link-type="dfn" href="#concept-event-listener">event listeners</a>. This can make the presence of listeners observable in
that even empty listeners can have a dramatic performance impact on the behavior of the application.
For example, touch and wheel events which can be used to block asynchronous scrolling. In some cases
this problem can be mitigated by specifying the event to be <code class="idl"><a data-link-type="idl" href="#dom-event-cancelable">cancelable</a></code> only when there is
at least one non-<code class="idl"><a data-link-type="idl" href="#dom-eventlisteneroptions-passive">passive</a></code> listener. For example,
non-<code class="idl"><a data-link-type="idl" href="#dom-eventlisteneroptions-passive">passive</a></code> <code class="idl"><a data-link-type="idl" href="https://www.w3.org/TR/touch-events/#touchevent-interface">TouchEvent</a></code> listeners must block scrolling, but if all
listeners are <code class="idl"><a data-link-type="idl" href="#dom-eventlisteneroptions-passive">passive</a></code> then scrolling can be allowed to start <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/infrastructure.html#in-parallel">in parallel</a> by making the <code class="idl"><a data-link-type="idl" href="https://www.w3.org/TR/touch-events/#touchevent-interface">TouchEvent</a></code> uncancelable (so that calls to <code class="idl"><a data-link-type="idl" href="#dom-event-preventdefault">preventDefault()</a></code> are ignored). So code dispatching an event is able to observe the absence
of non-<code class="idl"><a data-link-type="idl" href="#dom-eventlisteneroptions-passive">passive</a></code> listeners, and use that to clear the <code class="idl"><a data-link-type="idl" href="#dom-event-cancelable">cancelable</a></code> property of the event being dispatched. </p>
<p>Ideally, any new event APIs are defined such that they do not need this property (use <a href="https://lists.w3.org/Archives/Public/public-script-coord/">public-scrip-coord@w3.org</a> for discussion). </p>
<h3 class="heading settled" data-level="3.8" id="dispatching-events"><span class="secno">3.8. </span><span class="content">Dispatching events</span><a class="self-link" href="#dispatching-events"></a></h3>
<p>To <dfn data-dfn-for="Event" data-dfn-type="dfn" data-export="" id="concept-event-dispatch">dispatch<a class="self-link" href="#concept-event-dispatch"></a></dfn> an <var>event</var> to a <var>target</var>, with an optional <var>target override</var>, run these steps: </p>
<ol>
<li>
<p>Set <var>event</var>’s <a data-link-type="dfn" href="#dispatch-flag">dispatch flag</a>. </p>
<li>
<p>Initialize <var>event</var>’s <code class="idl"><a data-link-type="idl" href="#dom-event-target">target</a></code> attribute to <var>target override</var>, if it is given, and <var>target</var> otherwise. </p>
<li>
<p>Let <var>eventPath</var> be a list containing <var>target</var>. </p>
<li>
<p>While invoking <a data-link-type="dfn" href="#get-the-parent">get the parent</a>, given <var>event</var>, on <var>eventPath</var>’s
last item, does not return null, append the return value to <var>eventPath</var>. </p>
<li>
<p>Initialize <var>event</var>’s <code class="idl"><a data-link-type="idl" href="#dom-event-eventphase">eventPhase</a></code> attribute to <code class="idl"><a data-link-type="idl" href="#dom-event-capturing_phase">CAPTURING_PHASE</a></code>. </p>
<li>
<p>For each <var>object</var> in <var>eventPath</var>, in reverse order, if <var>event</var>’s <a data-link-type="dfn" href="#stop-propagation-flag">stop propagation flag</a> is unset and <var>object</var> is not <var>target</var>, <a data-link-type="dfn" href="#concept-event-listener-invoke">invoke</a> <var>object</var> with <var>event</var>. </p>
<li>
<p>Initialize <var>event</var>’s <code class="idl"><a data-link-type="idl" href="#dom-event-eventphase">eventPhase</a></code> attribute to <code class="idl"><a data-link-type="idl" href="#dom-event-at_target">AT_TARGET</a></code>. </p>
<li>
<p>If <var>event</var>’s <a data-link-type="dfn" href="#stop-propagation-flag">stop propagation flag</a> is unset, <a data-link-type="dfn" href="#concept-event-listener-invoke">invoke</a> <var>target</var> with <var>event</var>. </p>
<li>
<p>If <var>event</var>’s <code class="idl"><a data-link-type="idl" href="#dom-event-bubbles">bubbles</a></code> attribute value is true, run these substeps: </p>
<ol>
<li>
<p>Initialize <var>event</var>’s <code class="idl"><a data-link-type="idl" href="#dom-event-eventphase">eventPhase</a></code> attribute to <code class="idl"><a data-link-type="idl" href="#dom-event-bubbling_phase">BUBBLING_PHASE</a></code>. </p>
<li>
<p>For each <var>object</var> in <var>eventPath</var>, if <var>event</var>’s <a data-link-type="dfn" href="#stop-propagation-flag">stop propagation flag</a> is unset and <var>object</var> is not <var>target</var>, <a data-link-type="dfn" href="#concept-event-listener-invoke">invoke</a> <var>object</var> with <var>event</var>. </p>
</ol>
<li>
<p>Unset <var>event</var>’s <a data-link-type="dfn" href="#dispatch-flag">dispatch flag</a>. </p>
<li>
<p>Initialize <var>event</var>’s <code class="idl"><a data-link-type="idl" href="#dom-event-eventphase">eventPhase</a></code> attribute to <code class="idl"><a data-link-type="idl" href="#dom-event-none">NONE</a></code>. </p>
<li>
<p>Initialize <var>event</var>’s <code class="idl"><a data-link-type="idl" href="#dom-event-currenttarget">currentTarget</a></code> attribute to null. </p>
<li>
<p>Return false if <var>event</var>’s <a data-link-type="dfn" href="#canceled-flag">canceled flag</a> is set, and true otherwise. </p>
</ol>
<p>To <dfn data-dfn-for="event listener" data-dfn-type="dfn" data-noexport="" id="concept-event-listener-invoke">invoke<a class="self-link" href="#concept-event-listener-invoke"></a></dfn> an <var>object</var> with <var>event</var>, run these steps: </p>
<ol>
<li>
<p>Let <var>listeners</var> be the empty list. </p>
<li>
<p>For each <a data-link-type="dfn" href="#concept-event-listener">event listener</a> associated with <var>object</var>, append a pointer to the <a data-link-type="dfn" href="#concept-event-listener">event listener</a> to <var>listeners</var>. </p>
<p class="note no-backref" role="note">This avoids <a data-link-type="dfn" href="#concept-event-listener">event listeners</a> added after this point from being
run. Note that removal still has an effect due to the <b>removed</b> field. </p>
<li>
<p>Initialize <var>event</var>’s <code class="idl"><a data-link-type="idl" href="#dom-event-currenttarget">currentTarget</a></code> attribute to <var>object</var>. </p>
<li>
<p>Let <var>found</var> be the result of running <a data-link-type="dfn" href="#concept-event-listener-inner-invoke">inner invoke</a> <var>object</var> with <var>event</var>. </p>
<li>
<p>If <var>found</var> is false, run these substeps: </p>
<ol>
<li>
<p>Let <var>originalEventType</var> be <var>event</var>’s <code class="idl"><a data-link-type="idl" href="#dom-event-type">type</a></code> attribute value. </p>
<li>
<p>If <var>event</var>’s <code class="idl"><a data-link-type="idl" href="#dom-event-type">type</a></code> attribute value is a match for any of the strings in the
first column in the following table, set <var>event</var>’s <code class="idl"><a data-link-type="idl" href="#dom-event-type">type</a></code> attribute value to
the string in the second column on the same row as the matching string, and terminate these
substeps otherwise. </p>
<table>
<thead>
<tr>
<th>Event type
<th>Legacy event type
<tbody>
<tr>
<td>"<code>animationend</code>"
<td>"<code>webkitAnimationEnd</code>"
<tr>
<td>"<code>animationiteration</code>"
<td>"<code>webkitAnimationIteration</code>"
<tr>
<td>"<code>animationstart</code>"
<td>"<code>webkitAnimationStart</code>"
<tr>
<td>"<code>transitionend</code>"
<td>"<code>webkitTransitionEnd</code>"
</table>
<li>
<p><a data-link-type="dfn" href="#concept-event-listener-inner-invoke">Inner invoke</a> <var>object</var> with <var>event</var>. </p>
<li>
<p>Set <var>event</var>’s <code class="idl"><a data-link-type="idl" href="#dom-event-type">type</a></code> attribute value to <var>originalEventType</var>. </p>
</ol>
</ol>
<p>To <dfn data-dfn-for="event listener" data-dfn-type="dfn" data-noexport="" id="concept-event-listener-inner-invoke">inner invoke<a class="self-link" href="#concept-event-listener-inner-invoke"></a></dfn> an <var>object</var> with <var>event</var>, run these steps: </p>
<ol>
<li>
<p>Let <var>found</var> be false. </p>
<li>
<p>For each <var>listener</var> in <var>listeners</var>, whose <b>removed</b> is false, run
these substeps: </p>
<ol>
<li>
<p>If <var>event</var>’s <code class="idl"><a data-link-type="idl" href="#dom-event-type">type</a></code> attribute value is not <var>listener</var>’s <b>type</b>, terminate these substeps (and run them for the next <a data-link-type="dfn" href="#concept-event-listener">event listener</a>). </p>
<li>
<p>Set <var>found</var> to true. </p>
<li>
<p>If <var>event</var>’s <code class="idl"><a data-link-type="idl" href="#dom-event-eventphase">eventPhase</a></code> attribute value is <code class="idl"><a data-link-type="idl" href="#dom-event-capturing_phase">CAPTURING_PHASE</a></code> and <var>listener</var>’s <b>capture</b> is false, terminate these substeps (and run them for the
next <a data-link-type="dfn" href="#concept-event-listener">event listener</a>). </p>
<li>
<p>If <var>event</var>’s <code class="idl"><a data-link-type="idl" href="#dom-event-eventphase">eventPhase</a></code> attribute value is <code class="idl"><a data-link-type="idl" href="#dom-event-bubbling_phase">BUBBLING_PHASE</a></code> and <var>listener</var>’s <b>capture</b> is true, terminate these substeps (and run them for the next <a data-link-type="dfn" href="#concept-event-listener">event listener</a>). </p>
<li>
<p>If <var>listener</var>’s <b>passive</b> is true, set <var>event</var>’s <a data-link-type="dfn" href="#in-passive-listener-flag">in passive listener flag</a>. </p>
<li>
<p>Call <var>listener</var>’s <b>callback</b>’s <code class="idl"><a data-link-type="idl" href="#dom-eventlistener-handleevent">handleEvent()</a></code>, with <var>event</var> as argument and <var>event</var>’s <code class="idl"><a data-link-type="idl" href="#dom-event-currenttarget">currentTarget</a></code> attribute value as <a data-link-type="dfn" href="https://heycam.github.io/webidl/#dfn-callback-this-value">callback this value</a>. If this throws any exception, <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/webappapis.html#report-the-exception">report the exception</a>. </p>
<li>
<p>Unset <var>event</var>’s <a data-link-type="dfn" href="#in-passive-listener-flag">in passive listener flag</a>. </p>
<li>
<p>If <var>event</var>’s <a data-link-type="dfn" href="#stop-immediate-propagation-flag">stop immediate propagation flag</a> is set,
return <var>found</var>. </p>
</ol>
<li>
<p>Return <var>found</var>. </p>
</ol>
<h3 class="heading settled" data-level="3.9" id="firing-events"><span class="secno">3.9. </span><span class="content">Firing events</span><a class="self-link" href="#firing-events"></a></h3>
<p>To <dfn data-dfn-type="dfn" data-export="" data-lt="fire an event" id="concept-event-fire">fire an event named <var>e</var><a class="self-link" href="#concept-event-fire"></a></dfn> means that a new <a data-link-type="dfn" href="#concept-event">event</a> using the <code class="idl"><a data-link-type="idl" href="#event">Event</a></code> interface, with its <code class="idl"><a data-link-type="idl" href="#dom-event-type">type</a></code> attribute initialized to <var>e</var>, and its <code class="idl"><a data-link-type="idl" href="#dom-event-istrusted">isTrusted</a></code> attribute initialized to <code>true</code>, is to be <a data-link-type="dfn" href="#concept-event-dispatch">dispatched</a> to the given object.</p>
<p class="note no-backref" role="note">Fire in the context of DOM is short for creating, initializing,
and <a data-link-type="dfn" href="#concept-event-dispatch">dispatching</a> an <a data-link-type="dfn" href="#concept-event">event</a>. <a data-link-type="dfn" href="#concept-event-fire">Fire an event</a> makes that process easier to write
down. If the <a data-link-type="dfn" href="#concept-event">event</a> needs its <code class="idl"><a data-link-type="idl" href="#dom-event-bubbles">bubbles</a></code> or <code class="idl"><a data-link-type="idl" href="#dom-event-cancelable">cancelable</a></code> attribute initialized, one could write
"<a data-link-type="dfn" href="#concept-event-fire">fire an event</a> named <code>submit</code> with its <code class="idl"><a data-link-type="idl" href="#dom-event-cancelable">cancelable</a></code> attribute
initialized to true". </p>
<h3 class="heading settled" data-level="3.10" id="action-versus-occurance"><span class="secno">3.10. </span><span class="content">Action versus occurrence</span><a class="self-link" href="#action-versus-occurance"></a></h3>
<p>An <a data-link-type="dfn" href="#concept-event">event</a> signifies an occurrence, not an action. Phrased differently, it
represents a notification from an algorithm and can be used to influence the future course
of that algorithm (e.g., through invoking <code class="idl"><a data-link-type="idl" href="#dom-event-preventdefault">preventDefault()</a></code>). <a data-link-type="dfn" href="#concept-event">Events</a> must not be
used as actions or initiators that cause some algorithm to start running. That is not what
they are for. </p>
<p class="note no-backref" role="note">This is called out here specifically because previous
iterations of the DOM had a concept of "default actions" associated with <a data-link-type="dfn" href="#concept-event">events</a> that gave folks all the wrong ideas. <a data-link-type="dfn" href="#concept-event">Events</a> do not represent or cause actions, they
can only be used to influence an ongoing one. </p>
<h2 class="heading settled" data-level="4" id="nodes"><span class="secno">4. </span><span class="content">Nodes</span><a class="self-link" href="#nodes"></a></h2>
<h3 class="heading settled" data-level="4.1" id="introduction-to-the-dom"><span class="secno">4.1. </span><span class="content">Introduction to "The DOM"</span><a class="self-link" href="#introduction-to-the-dom"></a></h3>
<p>In its original sense, "The DOM" is an API for
accessing and manipulating documents (in particular, HTML and XML
documents). In this specification, the term "document" is used for any
markup-based resource, ranging from short static documents to long essays or
reports with rich multimedia, as well as to fully-fledged interactive
applications.</p>
<p>Each such document is represented as a <a data-link-type="dfn" href="#concept-node-tree">node tree</a>. Some of the <a data-link-type="dfn" href="#concept-node">nodes</a> in a <a data-link-type="dfn" href="#concept-tree">tree</a> can have <a data-link-type="dfn" href="#concept-tree-child">children</a>, while others are always leaves.</p>
<p>To illustrate, consider this HTML document:</p>
<pre class="lang-markup highlight"><span class="cp"><!DOCTYPE html></span>
<span class="nt"><html</span> <span class="na">class=</span><span class="s">e</span><span class="nt">></span>
<span class="nt"><head><title></span>Aliens?<span class="nt"></title></head></span>
<span class="nt"><body></span>Why yes.<span class="nt"></body></span>
<span class="nt"></html></span></pre>
<p>It is represented as follows:</p>
<ul class="domTree">
<li>
<a data-link-type="dfn" href="#concept-document">Document</a>
<ul>
<li class="t10"><a data-link-type="dfn" href="#concept-doctype">Doctype</a>: <code>html</code>
<li class="t1">
<code class="idl"><a data-link-type="idl" href="#element">Element</a></code>: <code>html</code> <span class="t2"><code class="attribute name">class</code>="<code class="attribute value">e</code>"</span>
<ul>
<li class="t1">
<code class="idl"><a data-link-type="idl" href="#element">Element</a></code>: <code>head</code>
<ul>
<li class="t1">
<code class="idl"><a data-link-type="idl" href="#element">Element</a></code>: <code>title</code>
<ul>
<li class="t3"><code class="idl"><a data-link-type="idl" href="#text">Text</a></code>: <span>Aliens?</span>
</ul>
</ul>
<li class="t3"><code class="idl"><a data-link-type="idl" href="#text">Text</a></code>: <span>⏎␣</span>
<li class="t1">
<code class="idl"><a data-link-type="idl" href="#element">Element</a></code>: <code>body</code>
<ul>
<li class="t3"><code class="idl"><a data-link-type="idl" href="#text">Text</a></code>: <span>Why yes.⏎</span>
</ul>
</ul>
</ul>
</ul>
<p>Note that, due to the magic that is <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/syntax.html#html-parser">HTML parsing</a>, not all <a data-link-type="dfn" href="https://encoding.spec.whatwg.org/#ascii-whitespace">ASCII whitespace</a> were turned into <code class="idl"><a data-link-type="idl" href="#text">Text</a></code> <a data-link-type="dfn" href="#concept-node">nodes</a>, but the general
concept is clear. Markup goes in, a <a data-link-type="dfn" href="#concept-tree">tree</a> of <a data-link-type="dfn" href="#concept-node">nodes</a> comes out.</p>
<p class="note no-backref" role="note">The most excellent <a href="http://software.hixie.ch/utilities/js/live-dom-viewer/">Live DOM Viewer</a> can be used to explore this matter in more detail. </p>
<h3 class="heading settled" data-level="4.2" id="node-trees"><span class="secno">4.2. </span><span class="content">Node tree</span><a class="self-link" href="#node-trees"></a></h3>
<p>Objects implementing the <code class="idl"><a data-link-type="idl" href="#document">Document</a></code>, <code class="idl"><a data-link-type="idl" href="#documentfragment">DocumentFragment</a></code>, <code class="idl"><a data-link-type="idl" href="#documenttype">DocumentType</a></code>, <code class="idl"><a data-link-type="idl" href="#element">Element</a></code>, <code class="idl"><a data-link-type="idl" href="#text">Text</a></code>, <code class="idl"><a data-link-type="idl" href="#processinginstruction">ProcessingInstruction</a></code>,
or <code class="idl"><a data-link-type="idl" href="#comment">Comment</a></code> interface (simply called <dfn data-dfn-type="dfn" data-export="" id="concept-node">nodes<a class="self-link" href="#concept-node"></a></dfn>) <a data-link-type="dfn" href="#concept-tree-participate">participate</a> in a <a data-link-type="dfn" href="#concept-tree">tree</a>, simply named the <dfn data-dfn-type="dfn" data-export="" id="concept-node-tree">node tree<a class="self-link" href="#concept-node-tree"></a></dfn>.</p>
<p>A <a data-link-type="dfn" href="#concept-node-tree">node tree</a> is constrained as
follows, expressed as a relationship between the type of <a data-link-type="dfn" href="#concept-node">node</a> and its allowed <a data-link-type="dfn" href="#concept-tree-child">children</a>:</p>
<dl>
<dt><code class="idl"><a data-link-type="idl" href="#document">Document</a></code>
<dd>
In <a data-link-type="dfn" href="#concept-tree-order">tree order</a>:
<ol>
<li>Zero or more nodes each of which is either <code class="idl"><a data-link-type="idl" href="#processinginstruction">ProcessingInstruction</a></code> or <code class="idl"><a data-link-type="idl" href="#comment">Comment</a></code>.
<li>Optionally one <code class="idl"><a data-link-type="idl" href="#documenttype">DocumentType</a></code> node.
<li>Zero or more nodes each of which is either <code class="idl"><a data-link-type="idl" href="#processinginstruction">ProcessingInstruction</a></code> or <code class="idl"><a data-link-type="idl" href="#comment">Comment</a></code>.
<li>Optionally one <code class="idl"><a data-link-type="idl" href="#element">Element</a></code> node.
<li>Zero or more nodes each of which is either <code class="idl"><a data-link-type="idl" href="#processinginstruction">ProcessingInstruction</a></code> or <code class="idl"><a data-link-type="idl" href="#comment">Comment</a></code>.
</ol>
<dt><code class="idl"><a data-link-type="idl" href="#documentfragment">DocumentFragment</a></code>
<dt><code class="idl"><a data-link-type="idl" href="#element">Element</a></code>
<dd>Zero or more nodes each of which is one of <code class="idl"><a data-link-type="idl" href="#element">Element</a></code>, <code class="idl"><a data-link-type="idl" href="#processinginstruction">ProcessingInstruction</a></code>, <code class="idl"><a data-link-type="idl" href="#comment">Comment</a></code>, or <code class="idl"><a data-link-type="idl" href="#text">Text</a></code>.
<dt><code class="idl"><a data-link-type="idl" href="#documenttype">DocumentType</a></code>
<dt><code class="idl"><a data-link-type="idl" href="#text">Text</a></code>
<dt><code class="idl"><a data-link-type="idl" href="#processinginstruction">ProcessingInstruction</a></code>
<dt><code class="idl"><a data-link-type="idl" href="#comment">Comment</a></code>
<dd>None.
</dl>
<p>The <dfn data-dfn-for="Node" data-dfn-type="dfn" data-export="" id="concept-node-length">length<a class="self-link" href="#concept-node-length"></a></dfn> of a <a data-link-type="dfn" href="#concept-node">node</a> <var>node</var> depends on <var>node</var>:</p>
<dl class="switch">
<dt><code class="idl"><a data-link-type="idl" href="#documenttype">DocumentType</a></code>
<dd>Zero.
<dt><code class="idl"><a data-link-type="idl" href="#text">Text</a></code>
<dt><code class="idl"><a data-link-type="idl" href="#processinginstruction">ProcessingInstruction</a></code>