html/DOM3-Events.html
author Gary Kacmarcik <garykac@google.com>
Fri, 23 May 2014 07:45:46 -0700
changeset 641 b1e8b052491a
parent 640 a10c8f662151
child 642 0601f18fe5c1
permissions -rw-r--r--
Update stacked event dispatch image (re-create as SVG).
411
70e31ba92e14 Fold changes from the 6 Sept "branch" back onto the mainline.
Gary Kacmarcik <garykac@google.com>
parents: 409
diff changeset
     1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
464
2471b17ce4f8 Enable floating "file a bug" div to spec to facilitate comments/feedback.
Gary Kacmarcik <garykac@google.com>
parents: 463
diff changeset
     2
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US"
2471b17ce4f8 Enable floating "file a bug" div to spec to facilitate comments/feedback.
Gary Kacmarcik <garykac@google.com>
parents: 463
diff changeset
     3
	data-bug-product='WebAppsWG'
2471b17ce4f8 Enable floating "file a bug" div to spec to facilitate comments/feedback.
Gary Kacmarcik <garykac@google.com>
parents: 463
diff changeset
     4
	data-bug-component='DOM3 Events'
2471b17ce4f8 Enable floating "file a bug" div to spec to facilitate comments/feedback.
Gary Kacmarcik <garykac@google.com>
parents: 463
diff changeset
     5
	>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
     6
<head>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
     7
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
     8
	<title>Document Object Model (DOM) Level 3 Events Specification</title>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
     9
	<link rel="author" href="mailto:www-dom@w3.org" />
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
    10
	<link rel="help" href="http://www.w3.org/DOM/" />
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
    11
	<link rel="alternate stylesheet" type="text/css" media="screen" title="geek" href="geek.css" />
411
70e31ba92e14 Fold changes from the 6 Sept "branch" back onto the mainline.
Gary Kacmarcik <garykac@google.com>
parents: 409
diff changeset
    12
	<link rel="stylesheet" type="text/css" href="spec-WD.css" />
436
be4894226f6d Use https for stylesheets to avoid security error on load.
Gary Kacmarcik <garykac@google.com>
parents: 435
diff changeset
    13
	<link rel="stylesheet" type="text/css" href="https://www.w3.org/StyleSheets/TR/w3c-tr.css" />
be4894226f6d Use https for stylesheets to avoid security error on load.
Gary Kacmarcik <garykac@google.com>
parents: 435
diff changeset
    14
	<link rel="stylesheet" type="text/css" href="https://www.w3.org/StyleSheets/TR/W3C-WD" />
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
    15
	<link rel="stylesheet" type="text/css" href="override.css" />
416
7c9bdb1ee920 Remove duplicate figure captions.
Gary Kacmarcik <garykac@google.com>
parents: 414
diff changeset
    16
	<script type="text/javascript" src='https://www.w3.org/Tools/respec/respec-w3c-common' class='remove' async></script>
457
e6c1ebba556e Correct internal links for WheelEvent, MouseEvent, UIEvent, KeyboardEvent, MutationEvent.
Gary Kacmarcik <garykac@google.com>
parents: 456
diff changeset
    17
	<script type="text/javascript" src='fixup.js'></script>
464
2471b17ce4f8 Enable floating "file a bug" div to spec to facilitate comments/feedback.
Gary Kacmarcik <garykac@google.com>
parents: 463
diff changeset
    18
	<script src="bug-assist.js"></script>
414
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    19
	<script type="text/javascript">
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    20
	var respecConfig = {
523
e85f7580093a Change back to ED
garykac@google.com
parents: 521
diff changeset
    21
		specStatus: "ED",
414
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    22
		shortName:  "DOM-Level-3-Events",
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    23
		editors: [
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    24
			{
427
eae783ac561c Revert to Editor's Draft
Gary Kacmarcik <garykac@google.com>
parents: 426
diff changeset
    25
				name: "Gary Kacmarcik", 
eae783ac561c Revert to Editor's Draft
Gary Kacmarcik <garykac@google.com>
parents: 426
diff changeset
    26
				company: "Google, Inc.",
eae783ac561c Revert to Editor's Draft
Gary Kacmarcik <garykac@google.com>
parents: 426
diff changeset
    27
				url: "mailto:garykac@google.com?subject=%5BDOM3-event%5D%20Spec%20Feedback",
eae783ac561c Revert to Editor's Draft
Gary Kacmarcik <garykac@google.com>
parents: 426
diff changeset
    28
				companyURL: "http://www.google.com",
eae783ac561c Revert to Editor's Draft
Gary Kacmarcik <garykac@google.com>
parents: 426
diff changeset
    29
				note: "Jun 2013 - present",
eae783ac561c Revert to Editor's Draft
Gary Kacmarcik <garykac@google.com>
parents: 426
diff changeset
    30
			},
eae783ac561c Revert to Editor's Draft
Gary Kacmarcik <garykac@google.com>
parents: 426
diff changeset
    31
			{
414
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    32
				name: "Travis Leithead", 
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    33
				company: "Microsoft Corp.",
416
7c9bdb1ee920 Remove duplicate figure captions.
Gary Kacmarcik <garykac@google.com>
parents: 414
diff changeset
    34
				url: "mailto:travis.leithead@microsoft.com?subject=%5BDOM3-event%5D%20Spec%20Feedback",
427
eae783ac561c Revert to Editor's Draft
Gary Kacmarcik <garykac@google.com>
parents: 426
diff changeset
    35
				companyURL: "http://www.microsoft.com",
eae783ac561c Revert to Editor's Draft
Gary Kacmarcik <garykac@google.com>
parents: 426
diff changeset
    36
				note: "Feb 2012 - present",
414
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    37
			},
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    38
			{
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    39
				name: "Jacob Rossi", 
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    40
				company: "Microsoft Corp.",
427
eae783ac561c Revert to Editor's Draft
Gary Kacmarcik <garykac@google.com>
parents: 426
diff changeset
    41
				note: "Mar 2011 - Oct 2011",
414
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    42
			},
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    43
			{
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    44
				name: "Doug Schepers", 
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    45
				company: "W3C",
427
eae783ac561c Revert to Editor's Draft
Gary Kacmarcik <garykac@google.com>
parents: 426
diff changeset
    46
				note: "Mar 2008 - May 2011",
414
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    47
			},
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    48
			{
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    49
				name: "Björn Höhrmann", 
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    50
				company: "Invited Expert",
427
eae783ac561c Revert to Editor's Draft
Gary Kacmarcik <garykac@google.com>
parents: 426
diff changeset
    51
				note: "until Jan 2008",
414
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    52
			},
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    53
			{
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    54
				name: "Philippe Le Hégaret", 
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    55
				company: "W3C",
427
eae783ac561c Revert to Editor's Draft
Gary Kacmarcik <garykac@google.com>
parents: 426
diff changeset
    56
				note: "until Nov 2003",
414
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    57
			},
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    58
			{
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    59
				name: "Tom Pixley", 
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    60
				company: "Netscape Communications Corporation",
427
eae783ac561c Revert to Editor's Draft
Gary Kacmarcik <garykac@google.com>
parents: 426
diff changeset
    61
				note: "until Jul 2002",
414
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    62
			}
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    63
		],
623
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
    64
		publishDate:  "2014-05-09",
456
987f6555fc6b Update hyperlinks which have been moved/redirected.
Gary Kacmarcik <garykac@google.com>
parents: 453
diff changeset
    65
		edDraftURI: "https://dvcs.w3.org/hg/dom3events/raw-file/tip/html/DOM3-Events.html",
523
e85f7580093a Change back to ED
garykac@google.com
parents: 521
diff changeset
    66
		previousPublishDate: "2013-11-05",
414
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    67
		previousMaturity: "WD",
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    68
		noIDLIn:  true,
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    69
		inlineCSS:  true,
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    70
		//noRecTrack:  true,
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
    71
		wg: ["Web Applications Working Group"],
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
    72
		wgURI: ["http://www.w3.org/2008/webapps/"],
414
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    73
		wgPublicList: "www-dom",
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    74
		wgPatentURI: ["http://www.w3.org/2004/01/pp-impl/42538/status"],
555
c638a959d36b Merge |code| information from UI Events.
Gary Kacmarcik <garykac@google.com>
parents: 552
diff changeset
    75
		maxTocLevel: 4
414
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    76
	};
b85ce1a25754 Temporary fix for xxx-idl -> d3-idl
Gary Kacmarcik <garykac@google.com>
parents: 413
diff changeset
    77
	</script>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
    78
</head>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
    79
<body>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
    80
	<!-- Section: Abstract ========================================================-->
413
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
    81
	<section id="abstract">
591
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
    82
		<p>This specification defines the Document Object Model Events Level 3, a generic
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
    83
			platform- and language-neutral event system which allows registration of event handlers,
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
    84
			describes event flow through a tree structure, and provides basic contextual
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
    85
			information for each event. The Document Object Model Events Level 3 builds on the
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
    86
			Document Object Model Events Level 2 [<a href="#references-DOM2Events">DOM2 Events</a>].
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
    87
			</p>
544
eb5cf0c88b21 Add comments after each </section>
garykac@google.com
parents: 543
diff changeset
    88
	</section>  <!-- abstract -->
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
    89
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
    90
	<!-- Section: SOTD ========================================================-->
413
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
    91
	<section id="sotd">
591
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
    92
		<p>This document is a Working Draft of the Document Object Model Level 3 Events
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
    93
			(DOM3 Events) specification. 
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
    94
			It is expected that this specification will progress to
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
    95
			<abbr title="World Wide Web Consortium">W3C</abbr> 
521
9e251e0967c9 Update respec source to remove Last Call info.
Gary Kacmarcik <garykac@google.com>
parents: 519
diff changeset
    96
			Recommendation status after review and refinement.
9e251e0967c9 Update respec source to remove Last Call info.
Gary Kacmarcik <garykac@google.com>
parents: 519
diff changeset
    97
			</p>
9e251e0967c9 Update respec source to remove Last Call info.
Gary Kacmarcik <garykac@google.com>
parents: 519
diff changeset
    98
9e251e0967c9 Update respec source to remove Last Call info.
Gary Kacmarcik <garykac@google.com>
parents: 519
diff changeset
    99
		<p id="this-document-is-produced-by-the-web-app">
591
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
   100
			This document is produced by the
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
   101
				<a href="http://www.w3.org/2008/webapps/">Web Applications WG</a>,
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
   102
			part of the
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
   103
				<a href="http://www.w3.org/2006/rwc/Activity">Rich Web Clients Activity</a>
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
   104
			in the W3C
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
   105
				<a href="http://www.w3.org/Interaction/">Interaction Domain</a>.
521
9e251e0967c9 Update respec source to remove Last Call info.
Gary Kacmarcik <garykac@google.com>
parents: 519
diff changeset
   106
			It is expected that this document will progress along the W3C's Recommendation track.
9e251e0967c9 Update respec source to remove Last Call info.
Gary Kacmarcik <garykac@google.com>
parents: 519
diff changeset
   107
			Publication as a Working Draft does not imply endorsement by the W3C Membership.
591
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
   108
			This is a draft document and MAY be updated, replaced or obsoleted by other
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
   109
			documents at any time.
521
9e251e0967c9 Update respec source to remove Last Call info.
Gary Kacmarcik <garykac@google.com>
parents: 519
diff changeset
   110
			It is inappropriate to cite this document as other than work in progress.
9e251e0967c9 Update respec source to remove Last Call info.
Gary Kacmarcik <garykac@google.com>
parents: 519
diff changeset
   111
			</p>
9e251e0967c9 Update respec source to remove Last Call info.
Gary Kacmarcik <garykac@google.com>
parents: 519
diff changeset
   112
9e251e0967c9 Update respec source to remove Last Call info.
Gary Kacmarcik <garykac@google.com>
parents: 519
diff changeset
   113
		<p id="latest-editors-draft">
9e251e0967c9 Update respec source to remove Last Call info.
Gary Kacmarcik <garykac@google.com>
parents: 519
diff changeset
   114
			<strong>You can find the latest
460
8b94685f205b Change W3C link from CVS to Mercurial (since that's where the ED lives now).
Gary Kacmarcik <garykac@google.com>
parents: 459
diff changeset
   115
				<a href="https://dvcs.w3.org/hg/dom3events/raw-file/tip/html/DOM3-Events.html">Editor's Draft</a>
8b94685f205b Change W3C link from CVS to Mercurial (since that's where the ED lives now).
Gary Kacmarcik <garykac@google.com>
parents: 459
diff changeset
   116
			of this document in the
8b94685f205b Change W3C link from CVS to Mercurial (since that's where the ED lives now).
Gary Kacmarcik <garykac@google.com>
parents: 459
diff changeset
   117
				<a href="https://dvcs.w3.org/hg/">W3C's Mercurial repository</a>,
521
9e251e0967c9 Update respec source to remove Last Call info.
Gary Kacmarcik <garykac@google.com>
parents: 519
diff changeset
   118
			which is updated on a regular basis.</strong>
9e251e0967c9 Update respec source to remove Last Call info.
Gary Kacmarcik <garykac@google.com>
parents: 519
diff changeset
   119
			</p>
9e251e0967c9 Update respec source to remove Last Call info.
Gary Kacmarcik <garykac@google.com>
parents: 519
diff changeset
   120
9e251e0967c9 Update respec source to remove Last Call info.
Gary Kacmarcik <garykac@google.com>
parents: 519
diff changeset
   121
		<p id="unstable">
9e251e0967c9 Update respec source to remove Last Call info.
Gary Kacmarcik <garykac@google.com>
parents: 519
diff changeset
   122
			<strong class="redNote">Implementers should be aware that this document is not stable.</strong>
591
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
   123
			Implementers who are not taking part in the discussions are likely to find the
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
   124
			specification changing out from under them in incompatible ways.
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
   125
			Vendors interested in implementing this document before it eventually reaches
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
   126
			the Candidate Recommendation stage should join the aforementioned mailing lists
eaeddc69551c Update Abstract and SOTD for D3E-key|code.
Gary Kacmarcik <garykac@google.com>
parents: 589
diff changeset
   127
			and take part in the discussions.
521
9e251e0967c9 Update respec source to remove Last Call info.
Gary Kacmarcik <garykac@google.com>
parents: 519
diff changeset
   128
			</p>
530
27e8c3727373 Fixup respect errors/warnings:
garykac@google.com
parents: 527
diff changeset
   129
	</section>  <!-- sotd -->
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   130
424
a0f0f1530035 Fix many typos, capitalization and minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 423
diff changeset
   131
	<!-- Section 1: DOM3 Events Overview  ========================================================-->
614
9dc74ec13aea Fix 25510 - Spec readability: Move glossary to the bottom
Travis Leithead
parents: 613
diff changeset
   132
	<section id="dom-events-intro">
9dc74ec13aea Fix 25510 - Spec readability: Move glossary to the bottom
Travis Leithead
parents: 613
diff changeset
   133
		<h1>Introduction</h1>
478
5913a35e9e16 Fix lots of typos and other minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 477
diff changeset
   134
		
413
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   135
		<section id="dom-events-overview">
614
9dc74ec13aea Fix 25510 - Spec readability: Move glossary to the bottom
Travis Leithead
parents: 613
diff changeset
   136
			<h2>Overview</h2>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   137
			<p>DOM Events is designed with two main goals. The first goal is the design of an <a class="def" href="#glossary-event">event</a> system which allows registration
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   138
				of event listeners and describes event flow through a tree structure. Additionally, the specification will provide standard modules of events for user interface
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   139
				control and document mutation notifications, including defined contextual information for each of these event modules.</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   140
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   141
			<p>The second goal of DOM Events is to provide a common subset of the current event systems used in existing browsers. This is intended to foster interoperability
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   142
				of existing scripts and content. It is not expected that this goal will be met with full backwards compatibility. However, the specification attempts to achieve
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   143
				this when possible.</p>
413
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   144
		</section>  <!-- dom-events-overview -->
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   145
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   146
		<section id="dom-events-conformance">
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   147
			<h2>Conformance</h2>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   148
			<p><strong>This section is normative.</strong></p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   149
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   150
			<p>Within this specification, the key words <q>MUST</q>, <q>MUST NOT</q>, <q>REQUIRED</q>,
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   151
				<q>SHALL</q>, <q>SHALL NOT</q>, <q>SHOULD</q>, <q>SHOULD NOT</q>,
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   152
				<q>RECOMMENDED</q>, <q>MAY</q>, and <q>OPTIONAL</q> are to be interpreted as described in
525
9056e78dc085 Fixup broken references: RFC2119, event-type-focusIn, interface-CompositionEvent
garykac@google.com
parents: 523
diff changeset
   153
				[<a href="#RFC2119">RFC2119</a>].</p>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   154
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   155
			<p>This specification is to be understood in the context of the DOM Level 3 Core specification [<cite><a class="normative" href="#references-DOMCore">DOM3 Core</a></cite>]
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   156
				and the general considerations for DOM implementations apply. For example, handling of <a class="def" href="#glossary-namespaceURI">namespace URIs</a> is discussed in
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   157
				<a class="normative" href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#Namespaces-Considerations"><em>XML Namespaces</em></a>. For additional information about
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   158
				<a class="normative" href="http://www.w3.org/TR/DOM-Level-3-Core/introduction.html#ID-Conformance"><em>conformance</em></a>, please see the DOM Level 3 Core specification
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   159
				[<cite><a class="normative" href="#references-DOMCore">DOM3 Core</a></cite>].  A <a class="def" href="#glossary-user-agent">user agent</a> is not required to conform
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   160
				to the entirety of another specification in order to conform to this specification, but it MUST conform to the specific parts of any other specification which are called
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   161
				out in this specification (e.g., a conforming DOM3 Events <a class="def" href="#glossary-user-agent">user agent</a> MUST support the <code>DOMString</code> data type as defined
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   162
				in <a href="#references-WebIDL">Web IDL</a>, but need not support every method or data type defined in <a href="#references-WebIDL">Web IDL</a> in order to conform
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   163
				to DOM3 Events).</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   164
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   165
			<p>This specification defines several classes of conformance for different <a class="def" href="#glossary-user-agent">user agents</a>, specifications, and content authors:</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   166
			<dl>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   167
				<dt id="conf-interactive-ua">Web browsers and other dynamic or interactive <a class="def" href="#glossary-user-agent">user agents</a></dt>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   168
				<dd>
594
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   169
					<p>A dynamic or interactive <a class="def" href="#glossary-user-agent">user agent</a>, referred to
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   170
						here as a <q>browser</q> (be it a Web browser, AT (Accessibility Technology) application,
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   171
						or other similar program), conforms to DOM Level 3 Events if it supports:
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   172
						</p>
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   173
					<ul>
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   174
						<li>the Core module defined in
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   175
							[<cite><a class="normative" href="#references-DOMCore">DOM3 Core</a></cite>]
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   176
							</li>
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   177
						<li>the <a href="#event-flow">Event dispatch and DOM event flow</a> mechanism
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   178
							</li>
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   179
						<li>all the interfaces and events with their associated methods, attributes, and
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   180
							semantics defined in this specification with the exception of those marked as
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   181
							<a class="def" href="#glossary-deprecated">deprecated</a> (a conforming user
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   182
							agent MAY implement the deprecated interfaces, events, or APIs for backwards
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   183
							compatibility, but is not required to do so in order to be conforming)
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   184
							</li>
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   185
						<li>the complete set of <code>key</code> and <code>code</code> values defined in
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   186
							[<a href="#references-D3E-key">DOM3 key Values</a>] and
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   187
							[<a href="#references-D3E-code">DOM3 code Values</a>]
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   188
							(subject to platform availability), and
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   189
							</li>
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   190
						<li>all other normative requirements defined in this specification.
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   191
							</li>
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   192
					</ul>
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   193
					<p>A conforming browser MUST <a class="def" href="#glossary-dispatch">dispatch</a> events appropriate
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   194
						to the given <a href="#interface-EventTarget">EventTarget</a> when the conditions defined
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   195
						for that <a class="def" href="#glossary-event-type">event type</a> have been met.
63dcb457c1c2 Update links D3E to refer to D3E-key and D3E-code specs where appropriate. Add Normative references.
Gary Kacmarcik <garykac@google.com>
parents: 591
diff changeset
   196
						</p>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   197
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   198
					<p><span id="conform-arch">A browser conforms specifically to the DOM Level 3 Events Architecture if it implements the <a href="#dom-event-architecture">DOM Event
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   199
						Architecture</a> and <a href="#event-interfaces">Basic Event Interfaces</a>, regardless of its support for any other event interfaces or <a class="def" href="#glossary-event-type">
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   200
						event types</a> defined in this specification.</span>  <span id="conform-module">A browser conforms specifically to the DOM Level 3 Events Module if it implements
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   201
						the interfaces and its related <a class="def" href="#glossary-event-type">event types</a> specified in the <a href="#events-module">Events Module</a>, and to each
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   202
						event interface if it implements that interface and its related <a class="def" href="#glossary-event-type">event types</a>.</span></p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   203
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   204
					<p><span id="conform-script">A conforming browser MUST support scripting, declarative interactivity, or some other means of detecting and dispatching events in the manner
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   205
						described by this specification, and MUST support the APIs specified for that <a class="def" href="#glossary-event-type">event type</a>.</span></p>
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   206
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   207
					<p>In addition to meeting all other conformance criteria, a conforming browser MAY implement features of this specification marked as <a class="def" href="#glossary-deprecated">
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   208
						deprecated</a>, for backwards compatibility with existing content, but such implementation is discouraged.</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   209
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   210
					<p>A conforming browser MAY also support features not found in this specification, but which use the <a href="#event-flow">Event dispatch and DOM event flow</a> mechanism,
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   211
						interfaces, events, or other features defined in DOM Level 3 Events, and MAY implement additional interfaces and <a class="def" href="#glossary-event-type">event types</a>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   212
						appropriate to that implementation. Such features can be later standardized in future specifications.</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   213
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   214
					<p>A browser which does not conform to all required portions of this specification MUST NOT claim conformance to DOM Level 3 Events.  Such an implementation which
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   215
						does conform to portions of this specification MAY claim conformance to those specific portions.</p>
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   216
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   217
					<p>A conforming browser MUST also be a <i>conforming implementation</i> of the IDL fragments in this specification, as described in the Web IDL specification. <a
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   218
						href="#references-WebIDL">[WEBIDL]</a></p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   219
				</dd>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   220
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   221
				<dt id="conf-author-tools">Authoring tools</dt>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   222
				<dd>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   223
					<p>A content authoring tool conforms to DOM Level 3 Events if it produces content which uses the <a class="def" href="#glossary-event-type">event types</a> and <a
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   224
						href="#event-flow">Event dispatch and DOM event flow</a> model, consistent in a manner as defined in this specification.  A content authoring tool MUST NOT claim
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   225
						conformance to DOM Level 3 Events for content it produces which uses features of this specification marked as <a class="def" href="#glossary-deprecated">deprecated</a>
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   226
						in this specification.  A conforming content authoring tool SHOULD provide to the content author a means to use all <a class="def" href="#glossary-event-type">event
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   227
						types</a> and interfaces appropriate to all <a class="def" href="#glossary-host-language">host languages</a> in the content document being produced.</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   228
				</dd>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   229
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   230
				<dt id="conf-authors">Content authors and content</dt>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   231
				<dd>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   232
					<p>A content author creates conforming DOM Level 3 Events content if that content uses the <a class="def" href="#glossary-event-type">event types</a> and <a href="#event-flow">
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   233
						Event dispatch and DOM event flow</a> model, consistent in a manner as defined in this specification.  A content author SHOULD NOT use features of this specification
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   234
						marked as <a class="def" href="#glossary-deprecated">deprecated</a>, but SHOULD rely instead upon replacement mechanisms defined in this specification and elsewhere.
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   235
						Conforming content MUST use the semantics of the interfaces and <a class="def" href="#glossary-event-type">event types</a> as described in this specification.</p>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   236
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   237
					<p class="note"><strong>Authoring Note: </strong>Content authors are advised to follow best practices as described in <a href="http://www.w3.org/TR/WAI-WEBCONTENT/">
377
ee9137a8840b Fixed various links which were reported with warnings and/or errors from the W3C's Link Checker.
tleithea
parents: 375
diff changeset
   238
						accessibility</a> and <a href="http://www.w3.org/standards/techs/i18n">internationalization</a> guideline specifications.</p>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   239
				</dd>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   240
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   241
				<dt id="conf-specs">Specifications and host languages</dt>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   242
				<dd>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   243
					<p>A specification or <a class="def" href="#glossary-host-language">host language</a> conforms to DOM Level 3 Events if it references and uses the <a href="#event-flow">
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   244
						Event dispatch and DOM event flow</a> mechanism, interfaces, events, or other features defined in this specification, and does not extend these
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   245
						features in incompatible ways.  A specification or <a class="def" href="#glossary-host-language">host language</a> conforms specifically to the DOM Level 3 Events
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   246
						Architecture if it references and uses the <a href="#dom-event-architecture">DOM Event Architecture</a> and <a href="#event-interfaces">Basic Event Interfaces</a>,
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   247
						regardless of its use of any other event interfaces or <a class="def" href="#glossary-event-type">event types</a> defined in this specification.</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   248
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   249
					<p>A specification or <a class="def" href="#glossary-host-language">host language</a> conforms specifically to the DOM Level 3 Events Module if it references and uses the interfaces and
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   250
						its related <a class="def" href="#glossary-event-type">event types</a> specified in the <a href="#events-module">Events Module</a>, and to each event interface
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   251
						if it references and uses that interface and its related <a class="def" href="#glossary-event-type">event types</a>. A conforming specification MAY
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   252
						define additional interfaces and <a class="def" href="#glossary-event-type">event types</a> appropriate to that specification, or MAY extend the DOM Level 3 Events
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   253
						interfaces and <a class="def" href="#glossary-event-type">event types</a> in a manner that does not contradict or conflict with the definitions of those interfaces
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   254
						and <a class="def" href="#glossary-event-type">event types</a> in this specification.</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   255
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   256
					<p>Specifications or <a class="def" href="#glossary-host-language">host languages</a> which reference DOM Level 3 Events SHOULD NOT use or recommend features of this
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   257
						specification marked as <a class="def" href="#glossary-deprecated">deprecated</a>, but SHOULD use or recommend the indicated replacement for that the feature (if available).</p>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   258
				</dd>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   259
			</dl>
413
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   260
		</section>  <!-- dom-events-conformance -->
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   261
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   262
		<section id="style-conventions">
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   263
			<h2>Stylistic Conventions</h2>
613
a5ef91af0785 Fix 25559 - Spec readability: Drop some obvious "stylistic conventions" definitions (Notes, Warnings, Examples)
Travis Leithead
parents: 611
diff changeset
   264
			<p>This specification follows the <a href="http://www.w3.org/People/Schepers/spec-conventions.html">Proposed W3C Specification
a5ef91af0785 Fix 25559 - Spec readability: Drop some obvious "stylistic conventions" definitions (Notes, Warnings, Examples)
Travis Leithead
parents: 611
diff changeset
   265
				Conventions</a>, with the following supplemental additions:</p>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   266
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   267
			<dl>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   268
				<dt>Key and character values</dt>
613
a5ef91af0785 Fix 25559 - Spec readability: Drop some obvious "stylistic conventions" definitions (Notes, Warnings, Examples)
Travis Leithead
parents: 611
diff changeset
   269
				<dd><ul>
623
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   270
					<li>Names of key values are shown as: <code class="key">'='</code> (e.g., the value of 
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   271
						<a href="#widl-KeyboardEvent-key"><code>KeyboardEvent.key</code></a>).
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   272
					<li>Names of key codes are shown as: <code class="code">'Equal'</code> (e.g., the value of 
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   273
						<a href="#widl-KeyboardEvent-code"><code>KeyboardEvent.code</code></a>).
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   274
					<li>Character values of keys are shown as: <code class="char">'\u003d'</code> (e.g., the code point 
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   275
						of the key value).
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   276
					<li>Glyphs representing character values are shown as: <code class="glyph">'='</code> (e.g., the
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   277
						<a href="#key-legends"><em>key cap</em></a> or font associated with a character value).
613
a5ef91af0785 Fix 25559 - Spec readability: Drop some obvious "stylistic conventions" definitions (Notes, Warnings, Examples)
Travis Leithead
parents: 611
diff changeset
   278
				</ul></dd>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   279
			</dl>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   280
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   281
			<p>In addition, certain terms are used in this specification with particular meanings.  The term <q>implementation</q> applies to a browser, content authoring tool,
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   282
				or other <a class="def" href="#glossary-user-agent">user agent</a> that implements this specification, while a content author is a person who writes script or code
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   283
				that takes advantage of the interfaces, methods, attributes, events, and other features described in this specification in order to make Web applications, and a
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   284
				user is the person who uses those Web applications in an implementation.</p>
413
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   285
		</section>  <!-- style-conventions -->
614
9dc74ec13aea Fix 25510 - Spec readability: Move glossary to the bottom
Travis Leithead
parents: 613
diff changeset
   286
	</section>  <!-- dom-events-intro -->
9dc74ec13aea Fix 25510 - Spec readability: Move glossary to the bottom
Travis Leithead
parents: 613
diff changeset
   287
9dc74ec13aea Fix 25510 - Spec readability: Move glossary to the bottom
Travis Leithead
parents: 613
diff changeset
   288
	<!-- Section 2: Issues ==============================================================-->
613
a5ef91af0785 Fix 25559 - Spec readability: Drop some obvious "stylistic conventions" definitions (Notes, Warnings, Examples)
Travis Leithead
parents: 611
diff changeset
   289
	<section id="issues">
a5ef91af0785 Fix 25559 - Spec readability: Drop some obvious "stylistic conventions" definitions (Notes, Warnings, Examples)
Travis Leithead
parents: 611
diff changeset
   290
		<h1>Issues</h1>
a5ef91af0785 Fix 25559 - Spec readability: Drop some obvious "stylistic conventions" definitions (Notes, Warnings, Examples)
Travis Leithead
parents: 611
diff changeset
   291
		
a5ef91af0785 Fix 25559 - Spec readability: Drop some obvious "stylistic conventions" definitions (Notes, Warnings, Examples)
Travis Leithead
parents: 611
diff changeset
   292
		<p class="issue">Open issues in this specification are called out using this convention.</p>
a5ef91af0785 Fix 25559 - Spec readability: Drop some obvious "stylistic conventions" definitions (Notes, Warnings, Examples)
Travis Leithead
parents: 611
diff changeset
   293
	</section>
614
9dc74ec13aea Fix 25510 - Spec readability: Move glossary to the bottom
Travis Leithead
parents: 613
diff changeset
   294
	
424
a0f0f1530035 Fix many typos, capitalization and minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 423
diff changeset
   295
	<!-- Section 3: Architecture ========================================================-->
413
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   296
	<section id="dom-event-architecture">
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   297
		<h1>DOM Event Architecture</h1>
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   298
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   299
		<section id="event-flow">
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   300
			<h2>Event dispatch and DOM event flow</h2>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   301
411
70e31ba92e14 Fold changes from the 6 Sept "branch" back onto the mainline.
Gary Kacmarcik <garykac@google.com>
parents: 409
diff changeset
   302
			<p>This section defines the event <a class="def" href="#glossary-dispatch">dispatch</a> mechanism of the event model defined in this specification.
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   303
				Applications MAY dispatch event objects using the <a href="#widl-EventTarget-dispatchEvent"><code>EventTarget.dispatchEvent()</code></a> method, and
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   304
				implementations MUST dispatch event objects as if through this method. The behavior of this method depends on the <em>event flow</em>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   305
				associated with the underlying object. An event flow describes how event objects <em>propagate</em> through a data structure. As an example, when an event object
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   306
				is dispatched to an element in an XML document, the object propagates through parts of the document, as determined by the DOM event flow which is defined at the
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   307
				end of this section.</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   308
530
27e8c3727373 Fixup respect errors/warnings:
garykac@google.com
parents: 527
diff changeset
   309
			<figure id="figure-dom-event-flow">
531
b2ec517923d6 Properly close <img /> tags.
garykac@google.com
parents: 530
diff changeset
   310
				<img src='images/eventflow.svg' width="520" height="560" />
530
27e8c3727373 Fixup respect errors/warnings:
garykac@google.com
parents: 527
diff changeset
   311
				<figcaption>Graphical representation of an event dispatched in a DOM tree using the DOM event flow</figcaption>
27e8c3727373 Fixup respect errors/warnings:
garykac@google.com
parents: 527
diff changeset
   312
			</figure>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   313
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   314
			<p>Event objects are dispatched to an <a class="def" href="#glossary-event-target">event target</a>. At the beginning
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   315
				of the dispatch, implementations MUST first determine the event object's <a class="def" href="#glossary-propagation-path">propagation path</a>.</p>
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   316
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   317
			<p>The propagation path MUST be an ordered list of <a class="def" href="#glossary-current-event-target">current event targets</a> through which
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   318
				the event object MUST pass. For DOM implementations, the propagation path MUST reflect the hierarchical tree
478
5913a35e9e16 Fix lots of typos and other minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 477
diff changeset
   319
				structure of the document. The last item in the list MUST be the <a class="def" href="#glossary-event-target">event target</a>. The
411
70e31ba92e14 Fold changes from the 6 Sept "branch" back onto the mainline.
Gary Kacmarcik <garykac@google.com>
parents: 409
diff changeset
   320
				preceding items in the list are referred to as the <em>target's ancestors</em>, and the immediately preceding item as the <em>target's parent</em>. Once determined, the
478
5913a35e9e16 Fix lots of typos and other minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 477
diff changeset
   321
				propagation path MUST NOT be changed. For DOM implementations, this applies even if an element in the propagation path is moved within the
441
d0dcec6e74c8 Fix minor typos.
Gary Kacmarcik <garykac@google.com>
parents: 440
diff changeset
   322
				DOM or removed from the DOM.</p>
411
70e31ba92e14 Fold changes from the 6 Sept "branch" back onto the mainline.
Gary Kacmarcik <garykac@google.com>
parents: 409
diff changeset
   323
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   324
			<div class="example">
472
52b0e71ee63d Auto-number the Examples.
Gary Kacmarcik <garykac@google.com>
parents: 471
diff changeset
   325
				<div class="example-title"></div>
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   326
				<p>In the DOM event flow, event listeners might change the position of the <a class="def" href="#glossary-event-target">
478
5913a35e9e16 Fix lots of typos and other minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 477
diff changeset
   327
				event target</a> in the document while the event object is being dispatched. Such changes do not affect the propagation path.</p>
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   328
			</div>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   329
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   330
			<p>Exceptions thrown inside event listeners MUST NOT stop the propagation of the event or affect the
424
a0f0f1530035 Fix many typos, capitalization and minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 423
diff changeset
   331
				<a class="def" href="#glossary-propagation-path">propagation path</a>. The exception itself MUST NOT propagate outside the scope of the event
389
9028f6a4b467 Fixing Bug: https://www.w3.org/Bugs/Public/show_bug.cgi?id=17714
tleithea
parents: 388
diff changeset
   332
				handler.</p>
9028f6a4b467 Fixing Bug: https://www.w3.org/Bugs/Public/show_bug.cgi?id=17714
tleithea
parents: 388
diff changeset
   333
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   334
			<div class="example">
472
52b0e71ee63d Auto-number the Examples.
Gary Kacmarcik <garykac@google.com>
parents: 471
diff changeset
   335
				<div class="example-title"></div>
424
a0f0f1530035 Fix many typos, capitalization and minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 423
diff changeset
   336
				<p>In the following code, the exception thrown from the call to <code>throw "Error"</code> does not propagate into the parent scope
389
9028f6a4b467 Fixing Bug: https://www.w3.org/Bugs/Public/show_bug.cgi?id=17714
tleithea
parents: 388
diff changeset
   337
				(which would prevent the <code>console.log</code> statement from executing):</p>
544
eb5cf0c88b21 Add comments after each </section>
garykac@google.com
parents: 543
diff changeset
   338
<pre>var e = document.createEvent("Event");
389
9028f6a4b467 Fixing Bug: https://www.w3.org/Bugs/Public/show_bug.cgi?id=17714
tleithea
parents: 388
diff changeset
   339
e.initEvent("myevent", false, false);
9028f6a4b467 Fixing Bug: https://www.w3.org/Bugs/Public/show_bug.cgi?id=17714
tleithea
parents: 388
diff changeset
   340
var target = document.createElement("div");
9028f6a4b467 Fixing Bug: https://www.w3.org/Bugs/Public/show_bug.cgi?id=17714
tleithea
parents: 388
diff changeset
   341
target.addEventListener("myevent", function () {
9028f6a4b467 Fixing Bug: https://www.w3.org/Bugs/Public/show_bug.cgi?id=17714
tleithea
parents: 388
diff changeset
   342
   throw "Error";
9028f6a4b467 Fixing Bug: https://www.w3.org/Bugs/Public/show_bug.cgi?id=17714
tleithea
parents: 388
diff changeset
   343
});
9028f6a4b467 Fixing Bug: https://www.w3.org/Bugs/Public/show_bug.cgi?id=17714
tleithea
parents: 388
diff changeset
   344
target.dispatchEvent(e); <span class="comment">// Causes the event listener to throw an exception...</span>
9028f6a4b467 Fixing Bug: https://www.w3.org/Bugs/Public/show_bug.cgi?id=17714
tleithea
parents: 388
diff changeset
   345
<span class="comment">// The previously thrown exception doesn't affect the code that follows:</span>
9028f6a4b467 Fixing Bug: https://www.w3.org/Bugs/Public/show_bug.cgi?id=17714
tleithea
parents: 388
diff changeset
   346
console.log("Exceptions? No problem");</pre>
9028f6a4b467 Fixing Bug: https://www.w3.org/Bugs/Public/show_bug.cgi?id=17714
tleithea
parents: 388
diff changeset
   347
			</div>
9028f6a4b467 Fixing Bug: https://www.w3.org/Bugs/Public/show_bug.cgi?id=17714
tleithea
parents: 388
diff changeset
   348
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   349
			<p id="event-phase">As the next step, the event object MUST complete one or more <a class="def" href="#glossary-phase">event phases</a>. This specification defines
424
a0f0f1530035 Fix many typos, capitalization and minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 423
diff changeset
   350
				three event phases: <a href="#capture-phase">capture phase</a>, <a href="#target-phase">target phase</a> and <a href="#bubble-phase">bubble phase</a>.  Event objects
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   351
				complete these phases in the specified order using the partial propagation paths as defined below. A phase MUST be skipped if it is not
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   352
				supported, or if the event object's propagation has been stopped. For example, if the <a href="#widl-Event-bubbles"><code>Event.bubbles</code></a>
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   353
				attribute is set to false, the bubble phase will be skipped, and if <a href="#widl-Event-stopPropagation"><code>Event.stopPropagation()</code></a> has been
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   354
				called prior to the dispatch, all phases MUST be skipped.</p>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   355
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   356
			<ol>
424
a0f0f1530035 Fix many typos, capitalization and minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 423
diff changeset
   357
				<li>The <strong id="capture-phase">capture phase</strong>: The event object MUST propagate through the target's ancestors from the <a class="def"
585
c2837d35f150 Fix 24797 - Stop using AbstractView
travil@microsoft.com
parents: 584
diff changeset
   358
					href="#glossary-window">Window</a> to the target's parent. This phase is also known as the <em>capturing phase</em>. Event
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   359
					listeners registered for this phase MUST handle the event before it reaches its target.</li>
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   360
424
a0f0f1530035 Fix many typos, capitalization and minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 423
diff changeset
   361
				<li>The <strong id="target-phase">target phase</strong>: The event object MUST arrive at the event object's <a class="def" href="#glossary-event-target">
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   362
					event target</a>. This phase is also known as the <em>at-target phase</em>. Event listeners registered for this phase MUST
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   363
					handle the event once it has reached its target. If the <a class="def" href="#glossary-event-type">event type</a> indicates that
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   364
					the event MUST NOT bubble, the event object MUST halt after completion of this phase.</li>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   365
424
a0f0f1530035 Fix many typos, capitalization and minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 423
diff changeset
   366
				<li>The <strong id="bubble-phase">bubble phase</strong>: The event object propagates through the target's ancestors in reverse order, starting
585
c2837d35f150 Fix 24797 - Stop using AbstractView
travil@microsoft.com
parents: 584
diff changeset
   367
					with the target's parent and ending with the <a class="def" href="#glossary-window">Window</a>. This phase is also known as the <em>bubbling phase</em>.
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   368
					Event listeners registered for this phase MUST handle the event after it has reached its target.</li>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   369
			</ol>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   370
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   371
			<p>Implementations MUST let event objects accomplish an event phase by applying the following steps while there are pending event targets in
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   372
				the partial propagation path for this phase and the event object's propagation has not been stopped through <a href="#widl-Event-stopPropagation"><code>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   373
				Event.stopPropagation()</code></a>.</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   374
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   375
			<p>First, the implementation MUST determine the <em>current target</em>. This MUST be the next pending event target in the partial propagation
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   376
				path, starting with the first. From the perspective of an event listener this MUST be the event target the listener has been registered on.</p>
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   377
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   378
			<p>Next, the implementation MUST determine the current target's <a class="def" href="#glossary-candidate-event-handlers">candidate event listeners</a>.
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   379
				This MUST be the list of all event listeners that have been registered on the current target in their order of registration. [<cite><a class="informative"
411
70e31ba92e14 Fold changes from the 6 Sept "branch" back onto the mainline.
Gary Kacmarcik <garykac@google.com>
parents: 409
diff changeset
   380
				href="#references-HTML5">HTML5</a></cite>] defines the ordering of listeners registered through event handler attributes. Once determined, the candidate event listeners
478
5913a35e9e16 Fix lots of typos and other minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 477
diff changeset
   381
				MUST NOT be changed. Adding or removing listeners does not affect the current target's candidate event listeners.</p>
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   382
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   383
			<p>Finally, the implementation MUST process all candidate <a class="def" href="#glossary-event-handler">event handlers</a> in order and trigger
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   384
				each handler if all the following conditions are met:</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   385
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   386
			<ul>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   387
				<li>The event object's immediate propagation has not been stopped.</li>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   388
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   389
				<li>The listener has been registered for this event phase.</li>
411
70e31ba92e14 Fold changes from the 6 Sept "branch" back onto the mainline.
Gary Kacmarcik <garykac@google.com>
parents: 409
diff changeset
   390
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   391
				<li>The listener has been registered for this <a class="def" href="#glossary-event-type">event type</a>.</li>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   392
			</ul>
411
70e31ba92e14 Fold changes from the 6 Sept "branch" back onto the mainline.
Gary Kacmarcik <garykac@google.com>
parents: 409
diff changeset
   393
585
c2837d35f150 Fix 24797 - Stop using AbstractView
travil@microsoft.com
parents: 584
diff changeset
   394
			<p>In the production of the <a class="def" href="#glossary-propagation-path">propagation path</a>, the event propagates from the <a class="def" href="#glossary-window">Window</a>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   395
				to the <code>document</code> object during the <a class="def" href="#glossary-capture-phase">capture phase</a>, and from the <code>document</code> object to the
585
c2837d35f150 Fix 24797 - Stop using AbstractView
travil@microsoft.com
parents: 584
diff changeset
   396
				<a class="def" href="#glossary-window">Window</a> during the <a class="def" href="#glossary-bubbling-phase">bubble phase</a>.</p>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   397
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   398
			<p>After an event completes all the phases of its <a class="def" href="#glossary-propagation-path">propagation path</a>, its <a href="#widl-Event-currentTarget">
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   399
				<code>Event.currentTarget</code></a> MUST be set to <code>null</code> and the <a href="#widl-Event-eventPhase"><code>Event.eventPhase</code></a> MUST be
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   400
				set to <code>0</code> (<a href="#widl-Event-NONE"><code>NONE</code></a>). All other attributes of the <code>Event</code> (or interface derived from <code>Event</code>)
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   401
				are unchanged (including the <a href="#widl-Event-target"><code>Event.target</code></a> attribute, which MUST continue to reference the <a class="def" href="#glossary-event-target">
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   402
				event target</a>).</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   403
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   404
			<p>The model defined above MUST be applied regardless of the specific event flow associated with an event target. Each event flow MUST define how the propagation path
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   405
				MUST be determined and which event phases are supported. The <em>DOM event flow</em> is an application of this model: the propagation path for a <code>Node</code>
585
c2837d35f150 Fix 24797 - Stop using AbstractView
travil@microsoft.com
parents: 584
diff changeset
   406
				object MUST be determined by its <code>Node.parentNode</code> chain, and if applicable, the document's containing <a class="def" href="#glossary-window">Window</a>.
478
5913a35e9e16 Fix lots of typos and other minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 477
diff changeset
   407
				All events accomplish the capture and target phases. Whether an event accomplishes the bubble phase MUST be defined individually for each <a class="def" href="#glossary-event-type">
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   408
				event type</a>. An alternate application of this model can be found in [<cite><a class="informative" href="#references-DOMLS">DOM3 Load and Save</a></cite>].</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   409
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   410
			<p>Implementations of the DOM event model MUST be reentrant. Event listeners MAY perform actions that cause additional events to be dispatched. Such events are handled
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   411
				in a synchronous manner, the event propagation that causes the event listener to be triggered MUST resume only after the event dispatch of the new event is completed.</p>
544
eb5cf0c88b21 Add comments after each </section>
garykac@google.com
parents: 543
diff changeset
   412
		</section>  <!-- event-flow -->
413
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   413
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   414
		<section id="event-flow-default-cancel">
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   415
			<h2>Default actions and cancelable events</h2>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   416
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   417
			<p>Events are typically dispatched by the implementation as a result of a user action, in response to the completion of a task, or to signal progress during asynchronous
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   418
				activity (such as a network request). Some events can be used to control the behavior that the implementation MAY take next (or undo an action that the implementation
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   419
				already took). Events in this category are said to be <em>cancelable</em> and the behavior they cancel is called their <a class="def" href="#glossary-default-action">
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   420
				<em>default action</em></a>. Cancelable event objects can be associated with one or more <a class="def" href="#glossary-default-action">default actions</a>.
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   421
				To cancel an event, call the <a href="#widl-Event-preventDefault"><code>Event.preventDefault()</code></a> method.</p>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   422
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   423
			<div class="example">
472
52b0e71ee63d Auto-number the Examples.
Gary Kacmarcik <garykac@google.com>
parents: 471
diff changeset
   424
				<div class="example-title"></div>
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   425
				<p>A <a class="eventtype" href="#event-type-mousedown"><code>mousedown</code></a> event is dispatched immediately after the user presses down a button on a
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   426
				pointing device (typically a mouse). One possible <a class="def" href="#glossary-default-action">default action</a> taken by the implementation is to set up a state
424
a0f0f1530035 Fix many typos, capitalization and minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 423
diff changeset
   427
				machine that allows the user to drag images or select text. The <a class="def" href="#glossary-default-action">default action</a> depends on what happens next &mdash; for
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   428
				example, if the user's pointing device is over text, a text selection might begin. If the user's pointing device is over an image, then an image-drag action could
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   429
				begin. Preventing the <a class="def" href="#glossary-default-action">default action</a> of a <a class="eventtype" href="#event-type-mousedown"><code>mousedown</code></a>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   430
				event prevents these actions from occuring.</p>
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   431
			</div>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   432
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   433
			<p><a class="def" href="#glossary-default-action">Default actions</a> SHOULD be performed after the event dispatch has been completed, but in exceptional
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   434
				cases MAY also be performed immediately before the event is dispatched.</p>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   435
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   436
			<div class="example">
472
52b0e71ee63d Auto-number the Examples.
Gary Kacmarcik <garykac@google.com>
parents: 471
diff changeset
   437
				<div class="example-title"></div>
424
a0f0f1530035 Fix many typos, capitalization and minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 423
diff changeset
   438
				<p>The default action associated with the <a class="eventtype" href="#event-type-click"><code>click</code></a> event on <code>&lt;input
a0f0f1530035 Fix many typos, capitalization and minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 423
diff changeset
   439
				type="checkbox"&gt;</code> elements toggles the <code>checked</code> IDL attribute value of that element. If the <a class="eventtype" href="#event-type-click"><code>click</code>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   440
				</a> event's default action is cancelled, then the value is restored to its former state.</p>
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   441
			</div>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   442
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   443
			<p id="events-dt-cancelable-event">When an event is canceled, then the conditional <a class="def" href="#glossary-default-action">default actions</a> associated with the event MUST be skipped (or
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   444
				as mentioned above, if the <a class="def" href="#glossary-default-action">default actions</a> are carried out before the dispatch, their effect MUST be undone).
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   445
				Whether an event object is cancelable MUST be indicated by the <a href="#widl-Event-cancelable"><code>Event.cancelable</code></a> attribute. <a href="#widl-Event-preventDefault">
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   446
				<code>Event.preventDefault()</code></a> stops all related <a class="def" href="#glossary-default-action">default actions</a> of an event object. The <a href="#widl-Event-defaultPrevented">
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   447
				<code>Event.defaultPrevented</code></a> attribute indicates whether an event has already been canceled (e.g., by a prior event listener). If the <a class="def" href="#glossary-DOM-application">
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   448
				DOM application</a> itself initiated the dispatch, then the return value of the <a href="#widl-EventTarget-dispatchEvent"><code>EventTarget.dispatchEvent()</code></a>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   449
				method indicates whether the event object was cancelled.</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   450
411
70e31ba92e14 Fold changes from the 6 Sept "branch" back onto the mainline.
Gary Kacmarcik <garykac@google.com>
parents: 409
diff changeset
   451
			<p class="note"><strong>Authoring Note: </strong>Many implementations additionally interpret an event listener's return value, such as the value <code>false</code>, to mean
70e31ba92e14 Fold changes from the 6 Sept "branch" back onto the mainline.
Gary Kacmarcik <garykac@google.com>
parents: 409
diff changeset
   452
				that the <a class="def" href="#glossary-default-action">default action</a> of cancelable events will be cancelled (though <code>window.onerror</code> handlers are cancelled
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   453
				by returning <code>true</code>).</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   454
478
5913a35e9e16 Fix lots of typos and other minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 477
diff changeset
   455
			<p class="note"><strong>Authoring Note: </strong>Some cancelable events might not have any observable <a class="def" href="#glossary-default-action">default actions</a>. For
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   456
				example, the <a class="eventtype" href="#event-type-mousemove"><code>mousemove</code></a> event.</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   457
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   458
			<p>This specification does not offer features to programatically query if an event object has any <a class="def" href="#glossary-default-action">default action</a> associated with
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   459
				it, or to associate new <a class="def" href="#glossary-default-action">default actions</a> with an event object. Other specifications SHOULD define what default actions, if any,
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   460
				are associated with certain event objects. Further, implementations MAY associate <a class="def" href="#glossary-default-action">default actions</a> with events as necessary and
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   461
				appropriate for that implementation.</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   462
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   463
			<div class="example">
472
52b0e71ee63d Auto-number the Examples.
Gary Kacmarcik <garykac@google.com>
parents: 471
diff changeset
   464
				<div class="example-title"></div>
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   465
				<p>As an example, one implementation might scroll a document view by a certain amount as the <a class="def" href="#glossary-default-action">
411
70e31ba92e14 Fold changes from the 6 Sept "branch" back onto the mainline.
Gary Kacmarcik <garykac@google.com>
parents: 409
diff changeset
   466
				default action</a> of a <a class="eventtype" href="#event-type-wheel"><code>wheel</code></a> event, while another implementation might instead zoom the document as its <a class="def"
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   467
				href="#glossary-default-action">default action</a>.</p>
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   468
			</div>
544
eb5cf0c88b21 Add comments after each </section>
garykac@google.com
parents: 543
diff changeset
   469
		</section>  <!-- event-flow-default-cancel -->
413
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   470
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   471
		<section id="sync-async">
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   472
			<h2>Synchronous and asynchronous events</h2>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   473
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   474
			<p>Events MAY be dispatched either synchronously or asynchronously.</p>
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   475
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   476
			<p>Events which are synchronous (<em><q>sync events</q></em>) MUST be treated as if they are in a virtual queue in a first-in-first-out model, ordered by sequence
424
a0f0f1530035 Fix many typos, capitalization and minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 423
diff changeset
   477
				of temporal occurrence with respect to other events, to changes in the DOM, and to user interaction.  Each event in this virtual queue MUST be delayed until the
478
5913a35e9e16 Fix lots of typos and other minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 477
diff changeset
   478
				previous event has completed its propagation behavior, or been canceled.  Some sync events are driven by a specific device or process, such as mouse button events.
5913a35e9e16 Fix lots of typos and other minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 477
diff changeset
   479
				These events are governed by the <a class="def" href="#glossary-event-order">event order</a> algorithms defined for that set of events, and a user agent MUST dispatch
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   480
				these events in the defined order.</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   481
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   482
			<div class="example">
472
52b0e71ee63d Auto-number the Examples.
Gary Kacmarcik <garykac@google.com>
parents: 471
diff changeset
   483
				<div class="example-title"></div>
560
d374e5b4fe8e Fix 23912 - 'Del' -> 'Delete'
Gary Kacmarcik <garykac@google.com>
parents: 559
diff changeset
   484
				<p>A user double-clicks a passage of text to select a word, then presses the <code class="key">'Delete'</code>
456
987f6555fc6b Update hyperlinks which have been moved/redirected.
Gary Kacmarcik <garykac@google.com>
parents: 453
diff changeset
   485
				key to erase the word, triggering the following synchronous sequence of events:
987f6555fc6b Update hyperlinks which have been moved/redirected.
Gary Kacmarcik <garykac@google.com>
parents: 453
diff changeset
   486
					<a class="eventtype" href="#event-type-mousedown"><code>mousedown</code></a>,
987f6555fc6b Update hyperlinks which have been moved/redirected.
Gary Kacmarcik <garykac@google.com>
parents: 453
diff changeset
   487
					<a class="eventtype" href="#event-type-mouseup"><code>mouseup</code></a>,
987f6555fc6b Update hyperlinks which have been moved/redirected.
Gary Kacmarcik <garykac@google.com>
parents: 453
diff changeset
   488
					<a class="eventtype" href="#event-type-click"><code>click</code></a>,
987f6555fc6b Update hyperlinks which have been moved/redirected.
Gary Kacmarcik <garykac@google.com>
parents: 453
diff changeset
   489
					<a class="eventtype" href="#event-type-mousedown"><code>mousedown</code></a>,
987f6555fc6b Update hyperlinks which have been moved/redirected.
Gary Kacmarcik <garykac@google.com>
parents: 453
diff changeset
   490
					<a class="eventtype" href="#event-type-mouseup"><code>mouseup</code></a>,
987f6555fc6b Update hyperlinks which have been moved/redirected.
Gary Kacmarcik <garykac@google.com>
parents: 453
diff changeset
   491
					<a class="eventtype" href="#event-type-click"><code>click</code></a>,
987f6555fc6b Update hyperlinks which have been moved/redirected.
Gary Kacmarcik <garykac@google.com>
parents: 453
diff changeset
   492
					<a class="eventtype" href="#event-type-dblclick"><code>dblclick</code></a>,
987f6555fc6b Update hyperlinks which have been moved/redirected.
Gary Kacmarcik <garykac@google.com>
parents: 453
diff changeset
   493
					<a class="eventtype" href="#event-type-select"><code>select</code></a>,
987f6555fc6b Update hyperlinks which have been moved/redirected.
Gary Kacmarcik <garykac@google.com>
parents: 453
diff changeset
   494
					<a class="eventtype" href="#event-type-keydown"><code>keydown</code></a>,
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   495
					<a class="eventtype" href="#event-type-beforeinput"><code>beforeinput</code></a>,
456
987f6555fc6b Update hyperlinks which have been moved/redirected.
Gary Kacmarcik <garykac@google.com>
parents: 453
diff changeset
   496
					<a class="eventtype" href="#event-type-input"><code>input</code></a>,
987f6555fc6b Update hyperlinks which have been moved/redirected.
Gary Kacmarcik <garykac@google.com>
parents: 453
diff changeset
   497
					<a class="eventtype" href="#event-type-keyup"><code>keyup</code></a>.
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   498
				Each of these events are fired in the sequence initiated by the user's actions.</p>
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   499
			</div>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   500
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   501
			<p>Events which are asynchronous (<em><q>async events</q></em>) MAY be dispatched as the results of the action are completed, with no relation to other events, to
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   502
				other changes in the DOM, nor to user interaction.</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   503
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   504
			<div class="example">
472
52b0e71ee63d Auto-number the Examples.
Gary Kacmarcik <garykac@google.com>
parents: 471
diff changeset
   505
				<div class="example-title"></div>
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   506
				<p>During loading of a document, an inline script element is parsed and executed. The <a class="eventtype" href="#event-type-load">
411
70e31ba92e14 Fold changes from the 6 Sept "branch" back onto the mainline.
Gary Kacmarcik <garykac@google.com>
parents: 409
diff changeset
   507
				<code>load</code></a> event is queued to be fired asynchronously at the script element. However, because it is an async event, its order with relation to other synchronous
530
27e8c3727373 Fixup respect errors/warnings:
garykac@google.com
parents: 527
diff changeset
   508
				events fired during document load (such as the <code class="eventtype">DOMContentLoaded</code> event from <cite><a class="informative" href="#references-HTML5">HTML5</a></cite>) is not guaranteed.</p>
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   509
			</div>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   510
413
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   511
			<section id="event-order-and-loops">
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   512
				<h3>Event order and event loops</h3>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   513
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   514
				<p>Most events take place in a sequential context.  [<cite><a class="informative" href="#references-HTML5">HTML5</a></cite>] defines its event operations in terms
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   515
					of an event loop mechanism, in which events of all types are fed into different <em>task queues</em>.  This specification does not define events in terms of this
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   516
					event loop mechanism, but it is compatible with this mechanism.  Instead, this specification defines several operation-specific <a class="def" href="#glossary-event-order">
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   517
					event orders</a>.</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   518
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   519
				<p>Using the terminology of HTML5, each independent device, such as a mouse or keyboard, SHOULD be treated as a <em>task source</em> which feeds into the appropriate
478
5913a35e9e16 Fix lots of typos and other minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 477
diff changeset
   520
					<em>task queue</em>, in the order defined by the <a class="def" href="#glossary-event-order">event order</a> associated with that device. Each operation, such as
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   521
					a focus change or composition input, also acts as a <em>task source</em> for the appropriate <em>task queue</em>.  The resolution of these event loops is handled
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   522
					in a manner conforming to the <a class="def" href="#glossary-host-language">host language</a>, such as HTML [<cite><a class="informative" href="#references-HTML5">HTML5</a></cite>].</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   523
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   524
				<p class="note"><strong>Authoring Note:</strong> Certain events, such as <q>hotkeys</q> or control keys pressed in a certain sequence, can be
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   525
					<q>swallowed</q> by the operating system or the application, interrupting the expected <a class="def" href="#glossary-event-order">event order</a>.</p>
544
eb5cf0c88b21 Add comments after each </section>
garykac@google.com
parents: 543
diff changeset
   526
			</section>  <!-- event-order-and-loops -->
eb5cf0c88b21 Add comments after each </section>
garykac@google.com
parents: 543
diff changeset
   527
		</section>  <!-- sync-async -->
413
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   528
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   529
		<section id="trusted-events">
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   530
			<h2>Trusted events</h2>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   531
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   532
			<p>Events that are generated by the user agent, either as a result of user interaction, or as a direct result of changes to the DOM, are trusted by the user agent
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   533
				with privileges that are not afforded to events generated by script through the <a href="#widl-DocumentEvent-createEvent"><code>DocumentEvent.createEvent("Event")</code></a>
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   534
				method, modified using the <a href="#widl-Event-initEvent"><code>Event.initEvent()</code></a> method, or dispatched via the <a href="#widl-EventTarget-dispatchEvent">
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   535
				<code>EventTarget.dispatchEvent()</code></a> method.  The <a href="#widl-Event-isTrusted"><code>isTrusted</code></a> attribute of trusted events has a
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   536
				value of <code>true</code>, while untrusted events have a <a href="#widl-Event-isTrusted"><code>isTrusted</code></a> attribute value of <code>false</code>.</p>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   537
599
ddb380ad70de Fix 25365 - About trusted="false" in two event orders
Travis Leithead
parents: 598
diff changeset
   538
			<p>Most untrusted events SHOULD NOT trigger <a class="def" href="#glossary-default-action">default actions</a>, with the exception of the <a class="eventtype" href="#event-type-click">
ddb380ad70de Fix 25365 - About trusted="false" in two event orders
Travis Leithead
parents: 598
diff changeset
   539
				<code>click</code></a> event. This event always triggers the <a class="def" href="#glossary-default-action">
ddb380ad70de Fix 25365 - About trusted="false" in two event orders
Travis Leithead
parents: 598
diff changeset
   540
				default action</a>, even if the <a href="#widl-Event-isTrusted"><code>isTrusted</code></a> attribute is <code>false</code> (this behavior is retained for backward-compatibility).
ddb380ad70de Fix 25365 - About trusted="false" in two event orders
Travis Leithead
parents: 598
diff changeset
   541
				All other untrusted events MUST behave
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   542
				as if the <a href="#widl-Event-preventDefault"><code>Event.preventDefault()</code></a> method had been called on that event.</p>
544
eb5cf0c88b21 Add comments after each </section>
garykac@google.com
parents: 543
diff changeset
   543
		</section>  <!-- trusted-events -->
413
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   544
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   545
		<section id="event-flow-activation">
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   546
			<h2>Activation triggers and behavior</h2>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   547
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   548
			<p>Certain <a class="def" href="#glossary-event-target">event targets</a> (such as a link or button element) MAY have associated <a class="def" href="#glossary-activation-behavior">
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   549
				activation behavior</a> (such a following a link) that implementations perform in response to an <em><a class="def" href="#glossary-activation-trigger">activation
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   550
				trigger</a></em> (such as clicking a link).</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   551
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   552
			<p>A <a class="def" href="#glossary-host-language">host language</a> SHOULD indicate which, if any, elements have activation behavior, describe appropriate <a class="def"
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   553
				href="#glossary-activation-trigger">activation triggers</a>, and define the result of that activation behavior.  An implementation which supports a <a class="def"
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   554
				href="#glossary-host-language">host language</a> SHOULD initiate these <a class="def" href="#glossary-activation-behavior">activation behavior</a> when the associated
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   555
				<a class="def" href="#glossary-activation-trigger">activation trigger</a> occurs.</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   556
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   557
			<div class="example" id="example-activation">
472
52b0e71ee63d Auto-number the Examples.
Gary Kacmarcik <garykac@google.com>
parents: 471
diff changeset
   558
				<div class="example-title"></div>
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   559
				<p>Both HTML and SVG have an <code>&lt;a&gt;</code> element which indicates a link.  Relevant <a
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   560
				class="def" href="#glossary-activation-trigger">activation triggers</a> for an <code>&lt;a&gt;</code> element are a <a class="eventtype" href="#event-type-click"><code>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   561
				click</code></a> event on the text or image  content of the <code>&lt;a&gt;</code> element, or a <a class="eventtype" href="#event-type-keydown"><code>keydown</code></a>
623
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   562
				event with a <a href="#widl-KeyboardEvent-key">key</a> attribute value of <code class="key">'Enter'</code> key when the <code>&lt;a&gt;</code>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   563
				element has focus.  The activation behavior for an <code>&lt;a&gt;</code> element is normally to change the content of the window to the content of the new document,
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   564
				in the case of external links, or to reposition the current document relative to the new anchor, in the case of internal links.</p>
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   565
			</div>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   566
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   567
			<p>An <a class="def" href="#glossary-activation-trigger">activation trigger</a> is a user action or an event which indicates to the implementation that an activation
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   568
				behavior SHOULD be initiated.  User-initiated <a class="def" href="#glossary-activation-trigger">activation triggers</a> include clicking a mouse button on an activatable
623
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   569
				element, pressing the <code class="key">'Enter'</code> key when an activatable element has focus, or pressing a key that is somehow
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   570
				linked to an activatable element (a <q>hotkey</q> or <q>access key</q>) even when that element does not have focus.  Event-based <a class="def" href="#glossary-activation-trigger">
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   571
				activation triggers</a> MAY include timer-based events that activate an element at a certain clock time or after a certain time period has elapsed, progress
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   572
				events after a certain action has been completed, or many other condition-based or state-based events.</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   573
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   574
			<p>In some cases, a <a class="def" href="#glossary-host-language">host language</a> MAY define attributes or even attribute values which add to or change the native
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   575
				<a class="def" href="#glossary-activation-trigger">activation trigger</a> or <a class="def" href="#glossary-activation-behavior">activation behavior</a> of an element.
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   576
				For example, ARIA [<cite><a class="informative" href="#ref-ARIA">ARIA</a></cite>] defines values for the <code class="attr">role</code> attribute that add semantics
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   577
				to the element to which it is applied, for purposes of enhanced accessibility.  In such cases, if the <a class="def" href="#glossary-host-language">host language</a>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   578
				does not explicitly define the <a class="def" href="#glossary-activation-trigger">activation trigger</a> or <a class="def" href="#glossary-activation-behavior">activation
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   579
				behavior</a>, the content author MUST provide the mechanics of the <a class="def" href="#glossary-activation-trigger">activation trigger</a> (via an event listener)
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   580
				or <a class="def" href="#glossary-activation-behavior">activation behavior</a> (such as calling an ECMAScript function) for that element when applying that attribute
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   581
				or attribute value.</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   582
413
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   583
			<section id="click-synthesis">
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   584
				<h3>Activation event synthesis</h3>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   585
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   586
				<p>If the instance of the <a class="def" href="#glossary-activation-trigger">activation trigger</a> is not an event of <a class="def" href="#glossary-event-type">event
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   587
					type</a> <a class="eventtype" href="#event-type-click"><code>click</code></a> (that is, when it does not result from a user's activation of a button or link
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   588
					using a mouse or equivalent pointing device), the implementation MUST synthesize and dispatch an event of <a class="def" href="#glossary-event-type">event type</a> <a
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   589
					class="eventtype" href="#event-type-click"><code>click</code></a> as one of the <a class="def" href="#glossary-default-action">default actions</a> of that <a class="def"
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   590
					href="#glossary-activation-trigger">activation trigger</a>. The value of the <code class="attribute-name"><a href="#widl-Event-target">Event.target</a></code>
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   591
					MUST be set to the <a class="def" href="#glossary-event-target">event target</a> (normally, the currently focused element), and the event MUST simulate a <em>left
457
e6c1ebba556e Correct internal links for WheelEvent, MouseEvent, UIEvent, KeyboardEvent, MutationEvent.
Gary Kacmarcik <garykac@google.com>
parents: 456
diff changeset
   592
					click</em> (i.e., the <a href="#widl-MouseEvent-button"><code>MouseEvent.button</code></a> attribute value MUST be <code>0</code>, and the <a href="#widl-MouseEvent-buttons">
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   593
					<code>MouseEvent.buttons</code></a> attribute value MUST be <code>1</code>).  Other context information of such a simulated <a class="eventtype" href="#event-type-click">
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   594
					<code>click</code></a> event is implementation dependent, but for historical purposes, the interface for the <a class="eventtype" href="#event-type-click"><code>click</code></a>
457
e6c1ebba556e Correct internal links for WheelEvent, MouseEvent, UIEvent, KeyboardEvent, MutationEvent.
Gary Kacmarcik <garykac@google.com>
parents: 456
diff changeset
   595
					event MUST be the <a href="#interface-MouseEvent"><code>MouseEvent interface</code></a>, regardless of the actual device used to activate the element.  Preventing
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   596
					the <a class="def" href="#glossary-default-action">default action</a> of the <a class="def" href="#glossary-activation-trigger">activation trigger</a>, such as
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   597
					with the <a href="#widl-Event-preventDefault"><code>Event.preventDefault()</code></a>, MUST stop the initiation of the <a class="def" href="#glossary-activation-behavior">
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   598
					activation behavior</a>.</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   599
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   600
				<div class="example">
472
52b0e71ee63d Auto-number the Examples.
Gary Kacmarcik <garykac@google.com>
parents: 471
diff changeset
   601
					<div class="example-title"></div>
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   602
					<p>When a user activates a hyperlink using a keyboard, such as by focusing the hyperlink element
623
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   603
					and pressing the <code class="key">'Enter'</code> or <code class="key">'&nbsp;'</code> key, a <a class="eventtype"
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   604
					href="#event-type-click"><code>click</code></a> event would be dispatched as the <a class="def" href="#glossary-default-action">default action</a> of the respective
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   605
					<a class="eventtype" href="#event-type-keydown"><code>keydown</code></a> event.</p>
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   606
				</div>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   607
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   608
				<p>Implementations MUST dispatch the synthesized <a class="eventtype" href="#event-type-click"><code>click</code></a> event as described above even if they do not
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   609
					normally dispatch such an event (e.g., when activation is requested by a voice command, since this specification does not address <a class="def" href="#glossary-event-type">
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   610
					event types</a> for voice input).</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   611
411
70e31ba92e14 Fold changes from the 6 Sept "branch" back onto the mainline.
Gary Kacmarcik <garykac@google.com>
parents: 409
diff changeset
   612
				<p class="note"><strong>Note:</strong> The activation of an event target is device dependent, but is also application dependent, e.g., a link in a document can be activated
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   613
					using a mouse click or a mouse double click.</p>
544
eb5cf0c88b21 Add comments after each </section>
garykac@google.com
parents: 543
diff changeset
   614
			</section>  <!-- click-synthesis -->
413
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   615
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   616
			<section id="events-activation-event-order">
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   617
				<h3>Activation event order</h3>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   618
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   619
				<p>Activation triggers and behavior can be defined in part by the events which are dispatched in a set order relative to one another.  The following is the typical
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   620
					sequence of events for an element activated by a pointing device (with only pertinent events listed):</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   621
463
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   622
				<table class="event-sequence-table">
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   623
					<tr>
623
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   624
						<td class="cell-number"></td>
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   625
						<th>Event Name</th>
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   626
						<th>Notes</th>
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   627
					</tr>
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   628
					<tr>
463
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   629
						<td class="cell-number">1.</td>
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   630
						<td><a class="eventtype" href="#event-type-click"><code>click</code></a></td>
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   631
						<td></td>
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   632
					</tr>
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   633
					<tr>
623
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   634
						<td class="cell-number"></td>
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   635
						<td></td>
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   636
						<td>
463
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   637
							<em>All <a class="def" href="#glossary-default-action">default actions</a>,
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   638
							including the <a class="def" href="#glossary-activation-behavior">activation behavior</a></em>
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   639
						</td>
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   640
					</tr>
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   641
				</table>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   642
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   643
				<p>The following is the typical sequence of events when a focused element is activated by a key event (with only pertinent events listed):</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   644
463
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   645
				<table class="event-sequence-table">
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   646
					<tr>
623
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   647
						<td class="cell-number"></td>
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   648
						<th>Event Name</th>
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   649
						<th>Notes</th>
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   650
					</tr>
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   651
					<tr>
463
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   652
						<td class="cell-number">1.</td>
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   653
						<td><a class="eventtype" href="#event-type-keydown"><code>keydown</code></a></td>
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   654
						<td>MUST be a key which can activate the element, such as the
623
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   655
							<code class="key">'Enter'</code> or <code class="key">'&nbsp;'</code> key,
463
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   656
							or the element is not activated</td>
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   657
					</tr>
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   658
					<tr>
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   659
						<td class="cell-number">2.</td>
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   660
						<td><a class="eventtype" href="#event-type-click"><code>click</code></a></td>
599
ddb380ad70de Fix 25365 - About trusted="false" in two event orders
Travis Leithead
parents: 598
diff changeset
   661
						<td><a class="def" href="#glossary-default-action">default action</a>; synthesized; <code>isTrusted="true"</code></td>
463
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   662
					</tr>
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   663
					<tr>
623
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   664
						<td class="cell-number"></td>
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   665
						<td></td>
a2c0d8dc96f5 Fix 25539 - Broken links and other correct
Travis Leithead
parents: 622
diff changeset
   666
						<td>
463
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   667
							<em>All <a class="def" href="#glossary-default-action">default actions</a>,
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   668
							including the <a class="def" href="#glossary-activation-behavior">activation behavior</a></em>
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   669
						</td>
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   670
					</tr>
1b4e14ed10f6 Update event order tables to use consistent formatting.
Gary Kacmarcik <garykac@google.com>
parents: 462
diff changeset
   671
				</table>
544
eb5cf0c88b21 Add comments after each </section>
garykac@google.com
parents: 543
diff changeset
   672
			</section>  <!-- events-activation-event-order -->
eb5cf0c88b21 Add comments after each </section>
garykac@google.com
parents: 543
diff changeset
   673
		</section>  <!-- event-flow-activation -->
413
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   674
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   675
		<section id="event-exceptions">
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   676
			<h2>Event exceptions</h2>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   677
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   678
			<p><em>This section is informative.</em></p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   679
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   680
			<p>Event operations can throw a <code>DOMException</code> as specified in their method descriptions.</p>
411
70e31ba92e14 Fold changes from the 6 Sept "branch" back onto the mainline.
Gary Kacmarcik <garykac@google.com>
parents: 409
diff changeset
   681
424
a0f0f1530035 Fix many typos, capitalization and minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 423
diff changeset
   682
			<p class="note" id="note-eventexcpetion-removed"><strong>Note:</strong> The exception <em>EventException</em> introduced in <strong class="version">DOM Level 2</strong> is
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   683
				removed in this specification as part of this specification's normative support of <a href="#references-WebIDL">Web IDL</a>. <em>EventException</em> formerly defined
411
70e31ba92e14 Fold changes from the 6 Sept "branch" back onto the mainline.
Gary Kacmarcik <garykac@google.com>
parents: 409
diff changeset
   684
				an exception code <code>UNSPECIFIED_EVENT_TYPE_ERR</code> which is replaced in this specification by the use of a <code>DOMException</code> of type
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   685
				<code>InvalidStateError</code>.</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   686
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   687
			<p>The following <code>DOMException</code> types are used in this specification.</p>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   688
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   689
			<table class="exceptiontable" summary="Layout table: the first cell contains the name of the DOMException type, the second contains a short description">
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   690
				<tr>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   691
					<th>Type</th>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   692
					<th>Description</th>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   693
				</tr>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   694
				<tr>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   695
					<td><code><dfn>InvalidStateError</dfn></code></td>
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   696
					<td>Thrown when the <a href="#widl-Event-type"><code>Event.type</code></a> was not specified by initializing the event before <code>dispatchEvent</code> was
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   697
						called. Also thrown when the <a href="#interface-Event"><code>Event</code></a> object provided to <code>dispatchEvent</code> is already being dispatched.</td>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   698
				</tr>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   699
				<tr>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   700
					<td><code><dfn>NotSupportedError</dfn></code></td>
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   701
					<td>Thrown when <a href="#widl-DocumentEvent-createEvent"><code>DocumentEvent.createEvent()</code></a> is passed an <a href="#interface-Event"><code>Event</code></a>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   702
						interface that the implementation does not support.</td>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   703
				</tr>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   704
			</table>
544
eb5cf0c88b21 Add comments after each </section>
garykac@google.com
parents: 543
diff changeset
   705
		</section>  <!-- event-exceptions -->
413
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   706
	</section>  <!-- dom-event-architecture -->
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   707
424
a0f0f1530035 Fix many typos, capitalization and minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 423
diff changeset
   708
	<!-- Section 4: Basic Event Interfaces ========================================================-->
413
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   709
	<section id="event-interfaces">
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   710
		<h1>Basic Event Interfaces</h1>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   711
551
7732919a7eaa Fold constructor info from Appendix into main text body for each event.
garykac@garykac-macbookair.roam.corp.google.com
parents: 550
diff changeset
   712
		<p>The interfaces described in this section are fundamental to DOM Level 3 Events and MUST
7732919a7eaa Fold constructor info from Appendix into main text body for each event.
garykac@garykac-macbookair.roam.corp.google.com
parents: 550
diff changeset
   713
			always be supported by the implementation.
7732919a7eaa Fold constructor info from Appendix into main text body for each event.
garykac@garykac-macbookair.roam.corp.google.com
parents: 550
diff changeset
   714
			</p>
7732919a7eaa Fold constructor info from Appendix into main text body for each event.
garykac@garykac-macbookair.roam.corp.google.com
parents: 550
diff changeset
   715
7732919a7eaa Fold constructor info from Appendix into main text body for each event.
garykac@garykac-macbookair.roam.corp.google.com
parents: 550
diff changeset
   716
		<p>The event types defined in this specification derive from these basic interfaces, and MUST
7732919a7eaa Fold constructor info from Appendix into main text body for each event.
garykac@garykac-macbookair.roam.corp.google.com
parents: 550
diff changeset
   717
			inherit all of the attributes, methods, and constants of the interfaces they derive from.
7732919a7eaa Fold constructor info from Appendix into main text body for each event.
garykac@garykac-macbookair.roam.corp.google.com
parents: 550
diff changeset
   718
			Event types defined in other specifications MAY similarly inherit from these basic interfaces
7732919a7eaa Fold constructor info from Appendix into main text body for each event.
garykac@garykac-macbookair.roam.corp.google.com
parents: 550
diff changeset
   719
			or other interfaces defined in this specification, or MAY define their own interfaces.
7732919a7eaa Fold constructor info from Appendix into main text body for each event.
garykac@garykac-macbookair.roam.corp.google.com
parents: 550
diff changeset
   720
			The following chart describes the inheritance structure of interfaces defined in this specification.
7732919a7eaa Fold constructor info from Appendix into main text body for each event.
garykac@garykac-macbookair.roam.corp.google.com
parents: 550
diff changeset
   721
			</p>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   722
530
27e8c3727373 Fixup respect errors/warnings:
garykac@google.com
parents: 527
diff changeset
   723
		<figure id="figure-event-inheritance">
531
b2ec517923d6 Properly close <img /> tags.
garykac@google.com
parents: 530
diff changeset
   724
			<img src='images/event-inheritance.svg' width="960" height="230" />
530
27e8c3727373 Fixup respect errors/warnings:
garykac@google.com
parents: 527
diff changeset
   725
			<figcaption>Graphical representation of the DOM3 Events interface inheritance</figcaption>
27e8c3727373 Fixup respect errors/warnings:
garykac@google.com
parents: 527
diff changeset
   726
		</figure>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   727
413
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   728
		<section id="interface-Event">
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
   729
			<h2>Interface Event</h2>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   730
421
47248706ce47 Use consistent formatting for "Introduced in DOM Level <n>" messages
Gary Kacmarcik <garykac@google.com>
parents: 419
diff changeset
   731
			<p class="intro-dom">Introduced in DOM Level 2</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   732
545
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   733
			<p>The <code>Event</code> interface provides basic contextual information about an event to
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   734
				all registered <a class="def" href="#glossary-event-handler">event handlers</a>.
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   735
				Specific events can also implement other derived interfaces, for example the
551
7732919a7eaa Fold constructor info from Appendix into main text body for each event.
garykac@garykac-macbookair.roam.corp.google.com
parents: 550
diff changeset
   736
					<a href="#interface-UIEvent"><code>UIEvent</code></a>
7732919a7eaa Fold constructor info from Appendix into main text body for each event.
garykac@garykac-macbookair.roam.corp.google.com
parents: 550
diff changeset
   737
				and
7732919a7eaa Fold constructor info from Appendix into main text body for each event.
garykac@garykac-macbookair.roam.corp.google.com
parents: 550
diff changeset
   738
					<a href="#interface-MouseEvent"><code>MouseEvent</code></a>
7732919a7eaa Fold constructor info from Appendix into main text body for each event.
garykac@garykac-macbookair.roam.corp.google.com
parents: 550
diff changeset
   739
				interfaces.
545
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   740
				</p>
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   741
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   742
			<p>To create an instance of the <code>Event</code> interface, use the
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   743
				<a href="#widl-DocumentEvent-createEvent"><code>DocumentEvent.createEvent("Event")</code></a>
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   744
				method call.
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   745
				</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   746
551
7732919a7eaa Fold constructor info from Appendix into main text body for each event.
garykac@garykac-macbookair.roam.corp.google.com
parents: 550
diff changeset
   747
			<dl class="idl" title="dictionary EventInit">
7732919a7eaa Fold constructor info from Appendix into main text body for each event.
garykac@garykac-macbookair.roam.corp.google.com
parents: 550
diff changeset
   748
				<dt>boolean bubbles = false</dt><dd></dd>
7732919a7eaa Fold constructor info from Appendix into main text body for each event.
garykac@garykac-macbookair.roam.corp.google.com
parents: 550
diff changeset
   749
				<dt>boolean cancelable = false</dt><dd></dd>
7732919a7eaa Fold constructor info from Appendix into main text body for each event.
garykac@garykac-macbookair.roam.corp.google.com
parents: 550
diff changeset
   750
			</dl>
7732919a7eaa Fold constructor info from Appendix into main text body for each event.
garykac@garykac-macbookair.roam.corp.google.com
parents: 550
diff changeset
   751
603
81dcf597c71b Fix 25359 - Use [Unforgeable] and [NewObject] annotations in D3E
Travis Leithead
parents: 601
diff changeset
   752
			<dl class="idl" title="[Constructor(DOMString typeArg, optional EventInit eventInitDict), Exposed=Window,Worker] interface Event">
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   753
				<dt>// PhaseType</dt>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   754
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   755
				<dt>const unsigned short NONE = 0</dt>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   756
				<dd>
637
58f7746cd6f7 Fix 25656 - [D3E] Another corrections and suggestions
Travis Leithead
parents: 634
diff changeset
   757
					<p>The current event is not being dispatched, i.e., the <a href="#widl-Event-eventPhase"><code>Event.eventPhase</code></a> is being observed prior to
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   758
						calling <a href="#widl-EventTarget-dispatchEvent">EventTarget.dispatchEvent()</a> or following the completion of the
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   759
						<a class="def" href="#glossary-phase">event phases</a> of a given <code>Event</code>.</p>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   760
				</dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   761
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   762
				<dt>const unsigned short CAPTURING_PHASE = 1</dt>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   763
				<dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   764
					<p>The current event phase is the <a class="def" href="#glossary-capture-phase">capture phase</a>.</p>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   765
				</dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   766
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   767
				<dt>const unsigned short AT_TARGET = 2</dt>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   768
				<dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   769
					<p>The current event is in the <a class="def" href="#glossary-target-phase">target phase</a>, i.e., it is being evaluated at the <a class="def"
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   770
						href="#glossary-event-target">event target</a>.</p>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   771
				</dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   772
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   773
				<dt>const unsigned short BUBBLING_PHASE = 3</dt>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   774
				<dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   775
					<p>The current event phase is the <a class="def" href="#glossary-bubbling-phase">bubbling phase</a>.</p>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   776
				</dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   777
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   778
				<dt>readonly attribute DOMString type</dt>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   779
				<dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   780
					<p>The name of the event type. <a href="#conf-specs">Specifications that define events</a>, <a href="#conf-authors">content authors</a>, and <a href="#conf-author-tools">
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   781
						authoring tools</a> MUST use case-sensitive event type names.</p>
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   782
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   783
					<p>The <a class="def" href="#glossary-un-initialized-value">un-initialized value</a> of this attribute MUST be <code>""</code> (the empty string).</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   784
				</dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   785
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   786
				<dt>readonly attribute EventTarget? target</dt>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   787
				<dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   788
					<p>Used to retrieve the <a class="def" href="#glossary-event-target">event target</a> associated with the <a href="#event-flow">Event dispatch and DOM
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   789
						event flow</a>.</p>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   790
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   791
					<p>The <a class="def" href="#glossary-un-initialized-value">un-initialized value</a> of this attribute MUST be <code>null</code>.</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   792
				</dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   793
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   794
				<dt>readonly attribute EventTarget? currentTarget</dt>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   795
				<dd>
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   796
					<p>Used to retrieve the <a class="def" href="#glossary-current-event-target">current event target</a> whose <a href="#interface-EventListener"><code>EventListeners</code></a>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   797
						are currently being processed. This is particularly useful during the capture and bubbling phases.</p>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   798
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   799
					<p>The <a class="def" href="#glossary-un-initialized-value">un-initialized value</a> of this attribute MUST be <code>null</code>.</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   800
				</dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   801
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   802
				<dt>readonly attribute unsigned short eventPhase</dt>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   803
				<dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   804
					<p>Used to indicate the <a href="#event-phase">phase</a> of the event's current propagation path (capture, target, or bubble).
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   805
						The event flow phases are defined in <a href="#event-flow">Event dispatch and DOM event flow</a>.</p>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   806
424
a0f0f1530035 Fix many typos, capitalization and minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 423
diff changeset
   807
					<p>The <a class="def" href="#glossary-un-initialized-value">un-initialized value</a> of this attribute MUST be <code>0</code> (<code>NONE</code>).</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   808
				</dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   809
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   810
				<dt>readonly attribute boolean bubbles</dt>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   811
				<dd>
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   812
					<p>Used to indicate whether or not an event is a bubbling event. If the event can bubble the value MUST be <code>true</code>, otherwise the value MUST be
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   813
						<code>false</code>.</p>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   814
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   815
					<p>The <a class="def" href="#glossary-un-initialized-value">un-initialized value</a> of this attribute MUST be <code>false</code>.</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   816
				</dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   817
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   818
				<dt>readonly attribute boolean cancelable</dt>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   819
				<dd>
547
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   820
					<p>Used to indicate whether or not an event can have its
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   821
							<a class="def" href="#glossary-default-action">default action</a>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   822
						prevented.
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   823
						If the
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   824
							<a class="def" href="#glossary-default-action">default action</a>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   825
						can be prevented the value MUST be <code>true</code>, otherwise the value
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   826
						MUST be <code>false</code>.
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   827
						See <a href="#event-flow-default-cancel">Default actions and cancelable events</a>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   828
						for more information on cancelable events.
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   829
						</p>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   830
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   831
					<p>The <a class="def" href="#glossary-un-initialized-value">un-initialized value</a>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   832
						of this attribute MUST be <code>false</code>.
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   833
						</p>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   834
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   835
					<p class="note"><strong>Note:</strong>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   836
						Use <code>Event.defaultPrevented</code> to see whether a cancelable event has
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   837
						been cancelled or not.
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   838
						</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   839
				</dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   840
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   841
				<dt>readonly attribute DOMTimeStamp timeStamp</dt>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   842
				<dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   843
					<p>Used to specify the time at which the event was created in milliseconds relative to 1970-01-01T00:00:00Z. This value is the <a class="def" href="#glossary-un-initialized-value">
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   844
						un-initialized value</a> of this attribute.</p>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   845
				</dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   846
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   847
				<dt>void stopPropagation()</dt>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   848
				<dd>
547
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   849
					<p>Prevents all other
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   850
							<a class="def" href="#glossary-event-handler">event listeners</a>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   851
						from being triggered for this event dispatch, <strong>excluding</strong> any remaining
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   852
							<a class="def" href="#glossary-candidate-event-handlers">candidate event listeners</a>.
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   853
						Once it has been called, further calls to this method have no additional effect.
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   854
						</p>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   855
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   856
					<p class="note" id="note-stopPropagation-default"><strong>Note:</strong>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   857
						This method does not prevent the
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   858
							<a class="def" href="#glossary-default-action">default action</a>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   859
						from being invoked &mdash; use
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   860
							<a href="#widl-Event-preventDefault"><code>Event.preventDefault()</code></a>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   861
						for that effect.
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   862
						</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   863
				</dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   864
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   865
				<dt>void preventDefault()</dt>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   866
				<dd>
547
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   867
					<p>When this method is invoked, the event MUST be canceled, meaning any
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   868
							<a class="def" href="#glossary-default-action">default actions</a>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   869
						normally taken by the implementation as a result of the event MUST NOT occur.
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   870
						Default actions which occur prior to the event's dispatch are reverted.
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   871
						Calling this method for a non-cancelable event MUST have no effect.
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   872
						If an event has more than one
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   873
							<a class="def" href="#glossary-default-action">default action</a>,
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   874
						each cancelable
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   875
							<a class="def" href="#glossary-default-action">default action</a>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   876
						MUST be canceled.
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   877
						See <a href="#event-flow-default-cancel">Default actions and cancelable events</a>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   878
						for more information on cancelable events.
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   879
						</p>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   880
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   881
					<p class="note"><strong>Note:</strong>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   882
						This method does not stop the event propagation &mdash; use
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   883
							<a href="#widl-Event-stopPropagation"><code>Event.stopPropagation()</code></a>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   884
						or
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   885
							<a href="#widl-Event-stopImmediatePropagation"><code>Event.stopImmediatePropagation()</code></a>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   886
						for that effect.
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   887
						</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   888
				</dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   889
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   890
				<dt>void initEvent()</dt>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   891
				<dd>
545
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   892
					<p>Initializes attributes of an <code>Event</code>.
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   893
						The <code>Event</code> could have been created through the
547
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   894
							<a href="#widl-DocumentEvent-createEvent"><code>DocumentEvent.createEvent</code></a>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   895
						method or by the implementation in response to a user action.
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   896
						For any <code>Event</code> created with the
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   897
							<a href="#widl-DocumentEvent-createEvent"><code>DocumentEvent.createEvent</code></a>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   898
						method, this method MUST be called before the <code>Event</code> is dispatched via the
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   899
							<a href="#widl-EventTarget-dispatchEvent"><code>EventTarget.dispatchEvent()</code></a>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   900
						method.
545
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   901
						If the method is called several times before invoking
547
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   902
							<a href="#widl-EventTarget-dispatchEvent"><code>EventTarget.dispatchEvent</code></a>,
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   903
						only the final invocation takes precedence.
545
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   904
						If this method is called during an invocation of
547
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   905
							<a href="#widl-EventTarget-dispatchEvent"><code>EventTarget.dispatchEvent</code></a>,
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   906
						this method MUST do nothing and return immediately.
545
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   907
						If called from a subclass of the <code>Event</code> interface only the values specified in
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   908
						this method are modified, all other attributes are left unchanged.
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   909
						</p>
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   910
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   911
					<p>This method MUST also reset the event object's internal-propagation and default-action-prevention states.
547
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   912
						This allows an event object to be "reset" before being dispatched multiple times.
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   913
						</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   914
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   915
					<div class="example">
472
52b0e71ee63d Auto-number the Examples.
Gary Kacmarcik <garykac@google.com>
parents: 471
diff changeset
   916
						<div class="example-title"></div>
545
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   917
						<p>If an <code>EventListener</code> called <code>stopPropagation()</code> or
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   918
							<code>stopImmediatePropagation()</code> during the event's previous dispatch, then after
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   919
							calling this method, the event can be re-dispatched (via <code>dispatchEvent</code>) and
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   920
							will propagate through all candidate event listeners along its propagation path (as it did
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   921
							during the prior dispatch).
547
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   922
							Similarly, if an <code>EventListener</code> called <code>preventDefault()</code>
545
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   923
							during the event's previous dispatch, then after calling this method, the event's
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   924
							<code>defaultPrevented</code> property will be <code>false</code>.
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   925
							</p>
418
4998aa3eb6a5 Consistent formatting for Examples, Notes and Warnings.
Gary Kacmarcik <garykac@google.com>
parents: 417
diff changeset
   926
					</div>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   927
545
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   928
					<p class="warning" id="warning-initEvent-untrusted"><strong>Warning!</strong>
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   929
						For security reasons, events modified using
547
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   930
							<a href="#widl-Event-initEvent"><code>Event.initEvent()</code></a>
599
ddb380ad70de Fix 25365 - About trusted="false" in two event orders
Travis Leithead
parents: 598
diff changeset
   931
						MUST have an
547
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   932
							<code class="attribute-name"><a href="#widl-Event-isTrusted">isTrusted</a></code>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   933
						attribute value of <code>false</code>.
545
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   934
						See <a href="#trusted-events">trusted events</a> for more details.
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   935
						</p>
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   936
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   937
					<p class="note"><strong>Authoring Note:</strong>
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   938
						<a class="def" href="#trusted-events">Trusted events</a> can have their
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   939
						<a class="def" href="#glossary-event-type">event type</a> and other attributes changed using this method.
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   940
						However, this method always converts the <code>Event</code> from a trusted event to an untrusted
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   941
						event (e.g., the <a href="#widl-Event-isTrusted"><code>Event.isTrusted</code></a> attribute will return
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   942
						<code>false</code>).
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   943
						</p>
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   944
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   945
					<p class="note"><strong>Authoring Note:</strong>
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   946
						<a class="def" href="#trusted-events">Trusted events</a> are pre-initialized by the implementation
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   947
						before being dispatched.
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   948
						As a result, it is not necessary to call <code>Event.initEvent()</code> prior to re-dispatching
547
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
   949
						the trusted event &mdash; however calling
545
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   950
						<a href="#widl-EventTarget-dispatchEvent"><code>EventTarget.dispatchEvent()</code></a> will convert
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   951
						the <code>Event</code> from a trusted event to an untrusted event (e.g., the
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   952
						<a href="#widl-Event-isTrusted"><code>Event.isTrusted</code></a> attribute will return <code>false</code>).
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   953
						</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   954
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   955
					<dl class="parameters">
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   956
						<dt>DOMString eventTypeArg</dt>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   957
						<dd>
545
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   958
							<p>Specifies <a href="#widl-Event-type"><code>Event.type</code></a>, the name of the event type.
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   959
								</p>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   960
						</dd>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   961
						
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   962
						<dt>boolean bubblesArg</dt>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   963
						<dd>
545
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   964
							<p>Specifies <a href="#widl-Event-bubbles"><code>Event.bubbles</code></a>.
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   965
								This parameter overrides the intrinsic bubbling behavior of the event.
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   966
								</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   967
						</dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   968
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   969
						<dt>boolean cancelableArg</dt>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   970
						<dd>
545
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   971
							<p>Specifies <a href="#widl-Event-cancelable"><code>Event.cancelable</code></a>.
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   972
								This parameter overrides the intrinsic cancelable behavior of the event.
90454480600e Reformat event initializer text for readability in prep for integrating the event initialization info from UI Events.
garykac@google.com
parents: 544
diff changeset
   973
								</p>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   974
						</dd>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   975
					</dl>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
   976
				</dd>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   977
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   978
				<dt>// Introduced in DOM Level 3</dt>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   979
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   980
				<dt>void stopImmediatePropagation()</dt>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   981
				<dd>
421
47248706ce47 Use consistent formatting for "Introduced in DOM Level <n>" messages
Gary Kacmarcik <garykac@google.com>
parents: 419
diff changeset
   982
					<p class="intro-dom">Introduced in DOM Level 3</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   983
441
d0dcec6e74c8 Fix minor typos.
Gary Kacmarcik <garykac@google.com>
parents: 440
diff changeset
   984
					<p>Prevents all other <a class="def" href="#glossary-event-handler">event listeners</a> from being triggered for this event dispatch, <strong>including</strong> any remaining
d0dcec6e74c8 Fix minor typos.
Gary Kacmarcik <garykac@google.com>
parents: 440
diff changeset
   985
						<a class="def" href="#glossary-candidate-event-handlers">candidate event listeners</a>. Once it has been called, further calls to this method have no additional
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   986
						effect.</p>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   987
478
5913a35e9e16 Fix lots of typos and other minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 477
diff changeset
   988
					<p class="note"><strong>Note:</strong> This method does not prevent the <a class="def" href="#glossary-default-action">default action</a> from being invoked &mdash;
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   989
						use <a href="#widl-Event-preventDefault"><code>Event.preventDefault()</code></a> for that effect.</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   990
				</dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   991
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   992
				<dt>readonly attribute boolean defaultPrevented</dt>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   993
				<dd>
421
47248706ce47 Use consistent formatting for "Introduced in DOM Level <n>" messages
Gary Kacmarcik <garykac@google.com>
parents: 419
diff changeset
   994
					<p class="intro-dom">Introduced in DOM Level 3</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
   995
					
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   996
					<p>Used to indicate whether this event has been cancelled or not. <code>Event.defaultPrevented</code> MUST return true if both <a href="#widl-Event-cancelable">
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
   997
						<code>Event.cancelable</code></a> is <code>true</code> and <a href="#widl-Event-preventDefault"><code>Event.preventDefault()</code></a> has been called for
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   998
						this event. Otherwise this attribute MUST return <code>false</code>.</p>
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
   999
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
  1000
					<p>The <a class="def" href="#glossary-un-initialized-value">un-initialized value</a> of this attribute MUST be <code>false</code>.</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1001
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
  1002
					<p class="note"><strong>Note:</strong> Calling <a href="#widl-Event-initEvent"><code>Event.initEvent()</code></a> after an event has been dispatched will reset
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1003
						the internal default-prevented state of the event.</p>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1004
				</dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1005
603
81dcf597c71b Fix 25359 - Use [Unforgeable] and [NewObject] annotations in D3E
Travis Leithead
parents: 601
diff changeset
  1006
				<dt>[Unforgeable] readonly attribute boolean isTrusted</dt>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1007
				<dd>
421
47248706ce47 Use consistent formatting for "Introduced in DOM Level <n>" messages
Gary Kacmarcik <garykac@google.com>
parents: 419
diff changeset
  1008
					<p class="intro-dom">Introduced in DOM Level 3</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1009
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1010
					<p>Used to indicate whether this event was generated by the <a class="def" href="#glossary-user-agent">user agent</a> (trusted) or by script (untrusted).  See <a
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1011
						href="#trusted-events">trusted events</a> for more details.</p>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1012
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
  1013
					<p>The <a class="def" href="#glossary-un-initialized-value">un-initialized value</a> of this attribute MUST be <code>false</code>.</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1014
				</dd>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
  1015
			</dl>
544
eb5cf0c88b21 Add comments after each </section>
garykac@google.com
parents: 543
diff changeset
  1016
		</section><!-- interface-Event -->
413
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
  1017
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
  1018
		<section id="interface-CustomEvent">
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
  1019
			<h2>Interface CustomEvent</h2>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1020
582
2afb1e76377f Fix 25295 - Various small fixes.
Gary Kacmarcik <garykac@google.com>
parents: 581
diff changeset
  1021
			<p class="intro-dom">Introduced in DOM Level 3</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1022
547
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
  1023
			<p>The <a href="#interface-CustomEvent"><code>CustomEvent</code></a> interface is the RECOMMENDED
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
  1024
				interface for application-specific event types.
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
  1025
				Unlike the <a href="#interface-Event"><code>Event</code></a> interface, it allows applications
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
  1026
				to provide contextual information about the event type.
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
  1027
				</p>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
  1028
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
  1029
			<p class="note"><strong>Authoring Note:</strong>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
  1030
				Use a prefix string on the event type name for application-specific event types to avoid
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
  1031
				clashes with future general-purpose event types.
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
  1032
				</p>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
  1033
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
  1034
			<p>To create an instance of the <code>CustomEvent</code> interface, use the
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
  1035
				<a href="#widl-DocumentEvent-createEvent"><code>DocumentEvent.createEvent("CustomEvent")</code></a>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
  1036
				method call.
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
  1037
				</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1038
568
eab211d2898a Fix 24741, CustomEvent inherits from Event
travil
parents: 564
diff changeset
  1039
			<dl class="idl" title="dictionary CustomEventInit : EventInit">
551
7732919a7eaa Fold constructor info from Appendix into main text body for each event.
garykac@garykac-macbookair.roam.corp.google.com
parents: 550
diff changeset
  1040
				<dt>any detail = null</dt><dd></dd>
7732919a7eaa Fold constructor info from Appendix into main text body for each event.
garykac@garykac-macbookair.roam.corp.google.com
parents: 550
diff changeset
  1041
			</dl>
7732919a7eaa Fold constructor info from Appendix into main text body for each event.
garykac@garykac-macbookair.roam.corp.google.com
parents: 550
diff changeset
  1042
603
81dcf597c71b Fix 25359 - Use [Unforgeable] and [NewObject] annotations in D3E
Travis Leithead
parents: 601
diff changeset
  1043
			<dl class="idl" title="[Constructor(DOMString typeArg, optional CustomEventInit customEventInitDict), Exposed=Window,Worker] interface CustomEvent : Event">
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1044
				<dt>readonly attribute any detail</dt>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
  1045
				<dd>
547
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
  1046
					<p>Specifies some detail information about the <a href="#interface-Event"><code>Event</code></a>.
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
  1047
						</p>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
  1048
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
  1049
					<p>The <a class="def" href="#glossary-un-initialized-value">un-initialized value</a>
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
  1050
						of this attribute MUST be <code>null</code>.
4cb42eaff74d Start re-writing text in Appendix A to remove references to updated constructor interfaces in UI Events.
garykac@google.com
parents: 546
diff changeset
  1051
						</p>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
  1052
				</dd>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
  1053
			</dl>
544
eb5cf0c88b21 Add comments after each </section>
garykac@google.com
parents: 543
diff changeset
  1054
		</section><!-- interface-CustomEvent -->
413
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
  1055
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
  1056
		<section id="interface-EventTarget">
7807985d4615 Convert document to use respec.
Gary Kacmarcik <garykac@google.com>
parents: 411
diff changeset
  1057
			<h2>Interface EventTarget</h2>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1058
582
2afb1e76377f Fix 25295 - Various small fixes.
Gary Kacmarcik <garykac@google.com>
parents: 581
diff changeset
  1059
			<p class="intro-dom">Introduced in DOM Level 2</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1060
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1061
			<p>The <code>EventTarget</code> interface allows registration and removal of event listeners, and dispatch of events to an event target.</p>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1062
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1063
			<p class="note"><strong>Note:</strong> Though an event listener can be registered for any <a class="def" href="#glossary-event-target">event
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1064
				target</a> node, the user agent only dispatches UA-generated (trusted) events on node types that are defined as event target types for that specific event type
424
a0f0f1530035 Fix many typos, capitalization and minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 423
diff changeset
  1065
				(see the <a href="#event-types-list">List of DOM3 Event Types</a>). For example, a <a class="eventtype" href="#event-type-mouseover"><code>mouseover</code></a>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1066
				event type registered on a text node will never be fired by the user agent, though a content author could dispatch an event of that type on the text node via script.</p>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1067
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
  1068
			<p>When used with the DOM event flow, this interface MUST be implemented by all <a class="def" href="#glossary-event-target">event targets</a> and target ancestors,
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1069
				i.e., all DOM <code>Nodes</code> of the tree support this interface when the implementation conforms to DOM Level 3 Events and, therefore, this interface can be
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1070
				obtained by using binding-specific casting methods on an instance of the <code>Node</code> interface.</p>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1071
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1072
			<p>Invoking <code>addEventListener</code> (or <code>removeEventListener</code>) repeatedly on the same <code>EventTarget</code> with the same values for the parameters
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1073
				<code>type</code>, <code>listener</code>, and <code>useCapture</code> has no effect. Doing so does not cause the event listener to be registered more than once and
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1074
				does not cause a change in the triggering order.</p>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1075
637
58f7746cd6f7 Fix 25656 - [D3E] Another corrections and suggestions
Travis Leithead
parents: 634
diff changeset
  1076
			<p class="note"><strong>Note:</strong>  In addition to the <a href="#widl-EventTarget-addEventListener"><code>EventTarget.addEventListener</code></a> method, some
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1077
				<a class="def" href="#glossary-host-language">host languages</a> allow a content author to register event listeners by the use of attributes, e.g.,
424
a0f0f1530035 Fix many typos, capitalization and minor formatting issues.
Gary Kacmarcik <garykac@google.com>
parents: 423
diff changeset
  1078
				<code>onclick="handleClick()"</code> (see [<cite><a class="informative" href="#references-HTML5">HTML5</a></cite>] for further examples). Due to the
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1079
				language-specific details, this type of event listener registration is not defined in this specification. In general, many event types can be used as an attribute
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1080
				in this way by adding the prefix <em><code>on-</code></em> to the event type name. Dispatching events to these listeners is expected to behave consistently with the
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1081
				event registration and propagation defined in this specification, with the same interfaces, properties, and methods.</p>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1082
603
81dcf597c71b Fix 25359 - Use [Unforgeable] and [NewObject] annotations in D3E
Travis Leithead
parents: 601
diff changeset
  1083
			<dl class="idl" title="[Exposed=Window,Worker] interface EventTarget">
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1084
				<dt>// Modified in DOM Level 3</dt>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1085
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1086
				<dt>void addEventListener()</dt>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
  1087
				<dd>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1088
					<p><em>Modified in DOM Level 3</em></p>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1089
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1090
					<p>Registers an event listener on the <a href="#interface-EventTarget"><code>EventTarget</code></a>. The listener is registered for the capture phase if the
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1091
						<code>useCapture</code> parameter is <code>true</code>, and for the bubble phase otherwise. When the event reaches the target element, listeners for both
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1092
						the capture and bubble phases are triggered as part of the target phase.
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1093
					</p>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1094
					
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1095
					<dl class="parameters">
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1096
						<dt>DOMString type</dt>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
  1097
						<dd>
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
  1098
							<p>Specifies the <a href="#widl-Event-type"><code>Event.type</code></a> associated with the event for which the user is registering.</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1099
						</dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1100
						
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1101
						<dt>EventListener? listener</dt>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1102
						<dd>
504
709178ecd5fb Note that mouse event order is normative.
Gary Kacmarcik <garykac@google.com>
parents: 503
diff changeset
  1103
							<p>If non-null, the <code>listener</code> parameter MUST be an object that implements the
709178ecd5fb Note that mouse event order is normative.
Gary Kacmarcik <garykac@google.com>
parents: 503
diff changeset
  1104
								<a href="#interface-EventListener"><code>EventListener</code></a> interface or a function.
709178ecd5fb Note that mouse event order is normative.
Gary Kacmarcik <garykac@google.com>
parents: 503
diff changeset
  1105
								If <code>listener</code> is a function then it MUST be used as the callback for the event.
709178ecd5fb Note that mouse event order is normative.
Gary Kacmarcik <garykac@google.com>
parents: 503
diff changeset
  1106
								Otherwise, if <code>listener</code> implements
709178ecd5fb Note that mouse event order is normative.
Gary Kacmarcik <garykac@google.com>
parents: 503
diff changeset
  1107
								<a href="#interface-EventListener"><code>EventListener</code></a>, then its
637
58f7746cd6f7 Fix 25656 - [D3E] Another corrections and suggestions
Travis Leithead
parents: 634
diff changeset
  1108
								<a href="#widl-EventListener-handleEvent"><code>handleEvent</code></a> method MUST be used as the callback.
504
709178ecd5fb Note that mouse event order is normative.
Gary Kacmarcik <garykac@google.com>
parents: 503
diff changeset
  1109
								</p>
561
1502cf07320b Fix 23186 - Add text indicating that addEventListener can accept null (and does nothing in that case)
Gary Kacmarcik <garykac@google.com>
parents: 560
diff changeset
  1110
							<p>If null is passed for the <code>listener</code>, then <code>addEventListener</code> does nothing.
1502cf07320b Fix 23186 - Add text indicating that addEventListener can accept null (and does nothing in that case)
Gary Kacmarcik <garykac@google.com>
parents: 560
diff changeset
  1111
								</p>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1112
						</dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1113
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1114
						<dt>optional boolean useCapture = false</dt>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1115
						<dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1116
							<p>If true, <code>useCapture</code> indicates that the user wishes to add the event listener for the <a class="def" href="#glossary-capture-phase">capture</a>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1117
								and <a class="def" href="#glossary-target-phase">target</a> phases only, i.e., this event listener will not be triggered during the <a class="def"
423
5913e7ca1b9a Remove manual formatting around MAY, SHOULD, MUST, et al.
Gary Kacmarcik <garykac@google.com>
parents: 422
diff changeset
  1118
								href="#glossary-bubbling-phase"> bubbling</a> phase. If <code>false</code>, the event listener MUST only be triggered during the <a class="def"
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1119
								href="#glossary-target-phase">target</a> and <a class="def" href="#glossary-bubbling-phase">bubbling</a> phases.</p>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1120
637
58f7746cd6f7 Fix 25656 - [D3E] Another corrections and suggestions
Travis Leithead
parents: 634
diff changeset
  1121
							<p>This parameter MUST be optional. If not provided, the <a href="#widl-EventTarget-addEventListener"><code>EventTarget.addEventListener</code></a> method MUST behave as if
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
  1122
								<code class="parameter-name">useCapture</code> was specified to be <code>false</code>.</p>
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
  1123
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
  1124
							<p class="note"><strong>Authoring Note:</strong>  The <code class="parameter-name">useCapture</code> parameter was mandatory in
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
  1125
								DOM2 Events [<a href="#references-DOM2Events">DOM2 Events</a>], and omitting this parameter could cause an error in older implementations.</p>
375
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
  1126
						</dd>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
  1127
					</dl>
573812ecd594 Updates for WD publication:
tleithea
parents: 373
diff changeset
  1128
				</dd>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1129
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1130
				<dt>void removeEventListener()</dt>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1131
				<dd>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1132
					<p><em>Modified in DOM Level 3</em></p>
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset
  1133
458
56ce2469eeb4 Correct remaining internal links to point to correct location.
Gary Kacmarcik <garykac@google.com>
parents: 457
diff changeset
  1134
					<p>Removes an event listener. Calling <code>removeEventListener</code> with arguments that do not identify any currently registered <a href="#interface-EventListener"><code>
417
3af9a4e6464d Use respec IDL formatting.
Gary Kacmarcik <garykac@google.com>
parents: 416
diff changeset