├── .github
├── PULL_REQUEST_TEMPLATE.md
└── workflows
│ └── auto-publish.yml
├── .gitignore
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE.md
├── README.md
├── build.py
├── dom-architecture.bs
├── dom-architecture.html
├── event-algo.bs
├── event-algo.html
├── images
├── event-inheritance.svg
├── eventflow.svg
└── stacked-event-mouse-dispatch.svg
├── index-snapshot.html
├── index.bs
├── proposals
├── d3e-keyflow.svg
├── dblclick.txt
├── keyflow-gecko.svg
├── mousewheel.txt
└── trident-keyflow.svg
├── sections
├── acknowledgements.txt
├── conventions.txt
├── event-compositionevent.txt
├── event-focusevent.txt
├── event-inputevent.txt
├── event-interfaces.txt
├── event-keyboardevent.txt
├── event-mouseevent.txt
├── event-uievent.txt
├── event-wheelevent.txt
├── extending-events.txt
├── external-algorithms.txt
├── glossary.txt
├── introduction.txt
├── keyboard.txt
├── legacy-event-initializers.txt
├── legacy-event-types.txt
├── legacy-key-attributes.txt
└── security.txt
├── stylesheet-extra.include
├── tests
├── key-mtest-101en-us.html
├── key-mtest-102fr-fr.html
├── key-mtest.css
└── key-mtest.js
├── tools
├── focus-event-viewer.css
├── focus-event-viewer.html
├── focus-event-viewer.js
├── key-event-viewer-ce.html
├── key-event-viewer.css
├── key-event-viewer.html
├── key-event-viewer.js
├── main.css
├── main.html
├── mouse-event-viewer-core.js
├── mouse-event-viewer-shadow.html
├── mouse-event-viewer-shadow.js
├── mouse-event-viewer-shared.js
├── mouse-event-viewer.css
├── mouse-event-viewer.html
├── options.js
└── output-table.js
└── w3c.json
/.github/PULL_REQUEST_TEMPLATE.md:
--------------------------------------------------------------------------------
1 | Closes #??
2 |
3 | The following tasks have been completed:
4 |
5 | * [ ] Confirmed there are no ReSpec/BikeShed errors or warnings.
6 | * [ ] Modified Web platform tests (link to pull request)
7 |
8 | Implementation commitment:
9 |
10 | * [ ] WebKit (https://bugs.webkit.org/show_bug.cgi?id=)
11 | * [ ] Chromium (https://bugs.chromium.org/p/chromium/issues/detail?id=)
12 | * [ ] Gecko (https://bugzilla.mozilla.org/show_bug.cgi?id=)
--------------------------------------------------------------------------------
/.github/workflows/auto-publish.yml:
--------------------------------------------------------------------------------
1 | name: CI
2 | on:
3 | pull_request: {}
4 | push:
5 | branches: [main]
6 | jobs:
7 | main:
8 | name: Build, Validate, Deploy
9 | runs-on: ubuntu-latest
10 | steps:
11 | - uses: actions/checkout@v2
12 | - run: python build.py --includes-only
13 | - uses: w3c/spec-prod@v2
14 | with:
15 | GH_PAGES_BRANCH: gh-pages
16 | TOOLCHAIN: bikeshed
17 | BUILD_FAIL_ON: "link-error"
18 | W3C_NOTIFICATIONS_CC: ${{ secrets.CC }}
19 | W3C_ECHIDNA_TOKEN: ${{ secrets.ECHIDNA_TOKEN }}
20 | W3C_WG_DECISION_URL: https://lists.w3.org/Archives/Public/public-webapps/2014JulSep/0627.html
21 | W3C_BUILD_OVERRIDE: |
22 | status: WD
23 | shortname: uievents
24 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | .DS_Store
2 |
3 | # These files are generated by the build.py script and should not
4 | # be checked in.
5 | sections/*.include
6 | index.html
7 |
--------------------------------------------------------------------------------
/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
1 | # Code of Conduct
2 |
3 | All documentation, code and communication under this repository are covered by the [W3C Code of Ethics and Professional Conduct](https://www.w3.org/Consortium/cepc/).
4 |
--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
1 | # Web Platform Working Group
2 |
3 | Contributions to this repository are intended to become part of
4 | Recommendation-track documents governed by the
5 | [W3C Patent Policy](http://www.w3.org/Consortium/Patent-Policy-20040205/)
6 | and
7 | [Software and Document License](http://www.w3.org/Consortium/Legal/copyright-software).
8 | To make substantive contributions to specifications, you must either participate
9 | in the W3C
10 | [Web Platform Working Group](https://www.w3.org/WebPlatform/WG/)
11 | or make a
12 | [non-member patent licensing commitment](https://www.w3.org/2004/01/pp-impl/83482/nmlc).
13 |
14 | If you are not the sole contributor to a contribution (pull request), please
15 | identify all contributors in the pull request comment.
16 |
17 | To add a contributor (other than yourself, that's automatic), mark them one per
18 | line as follows:
19 |
20 | ```
21 | +@github_username
22 | ```
23 |
24 | If you added a contributor by mistake, you can remove them in a comment with:
25 |
26 | ```
27 | -@github_username
28 | ```
29 |
30 | If you are making a pull request on behalf of someone else but you had no part
31 | in designing the feature, you can remove yourself with the above syntax.
32 |
33 | # Tests
34 |
35 | For normative changes, a corresponding
36 | [web-platform-tests](https://github.com/web-platform-tests/wpt) PR is highly appreciated. Typically,
37 | both PRs will be merged at the same time. Note that a test change that contradicts the spec should
38 | not be merged before the corresponding spec change. If testing is not practical, please explain why
39 | and if appropriate [file an issue](https://github.com/web-platform-tests/wpt/issues/new) to follow
40 | up later. Add the `type:untestable` or `type:missing-coverage` label as appropriate.
41 |
--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
1 | All documents in this Repository are licensed by contributors
2 | under the
3 | [W3C Software and Document License](http://www.w3.org/Consortium/Legal/copyright-software).
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # UI Events
2 |
3 | This repository is for the [UI Events specification](https://w3c.github.io/uievents/) (formerly known as DOM 3 Events).
4 |
5 | ## Goals
6 |
7 | The goal of the UI/DOM Events sub-group, part of the Web Applications Working Group, is to complete the
8 | UI Events specification according to market needs, to drive its adoption and implementation, to provide
9 | a comprehensive test suite (for implementability at least, and hopefully for interoperability, too),
10 | and to move it along the Recommendation Track to W3C Recommendation status.
11 |
12 | ## Communication
13 |
14 | For discussion of matters related to DOM Events, the group uses the www-dom@w3.org mailing list ([archive](http://lists.w3.org/Archives/Public/www-dom/)).
15 |
16 | ## Documents
17 |
18 | * Published Documents
19 | * [UI Events - Last Published WD](http://www.w3.org/TR/uievents/)
20 | * [DOM Level 3 KeyboardEvent key Values](http://www.w3.org/TR/DOM-Level-3-Events-key/)
21 | * [DOM Level 3 KeyboardEvent code Values](http://www.w3.org/TR/DOM-Level-3-Events-code/)
22 | * Editor's Drafts
23 | * [UI Events](https://w3c.github.io/uievents/)
24 | * [UI Events KeyboardEvent key Values](https://w3c.github.io/uievents-key/)
25 | * [UI Events KeyboardEvent code Values](https://w3c.github.io/uievents-code/)
26 |
27 | ## Open Issues
28 |
29 | * [UI Events Issues Database](https://github.com/w3c/uievents/issues)
30 | * Need for detailed review by implementors
31 | * Need for comprehensive test suite
32 | * [key Values Issues](https://github.com/w3c/uievents-key/issues)
33 | * [code Values Issues](https://github.com/w3c/uievents-code/issues)
34 |
35 | ## Building
36 |
37 | This spec was created using [bikeshed](https://github.com/tabatkins/bikeshed).
38 | If you would like to contribute edits, please make sure that your changes
39 | build correctly.
40 |
41 | To **build** this spec:
42 |
43 | 1. Clone this repo into a local directory.
44 | 1. Install [bikeshed](https://github.com/tabatkins/bikeshed)
45 | 1. Run `python build.py` in your local directory.
46 |
47 | To **make edits** to the spec:
48 |
49 | 1. Edit the `index.bs` file or any of the `sections\*.txt` files.
50 | 2. Build (as above). This will create a `sections\*.include` file for each
51 | `*.txt` file and then create the `index.html`.
52 |
53 | When submitting pull requests, make sure you don't include any of the
54 | `sections\*.include` files in your changelist — they've all been added to the
55 | `.gitignore` file so that you don't include them accidentally. All changes
56 | should be made in the `sections\*.txt` files and `index.bs`.
57 |
58 | ## Testing
59 |
60 | * [DomEventViewer](https://domeventviewer.com/) for testing UI Events
61 | * Web Platform Tests
62 | * [GitHub web-platform-tests/wpt uievents](https://github.com/web-platform-tests/wpt/tree/master/uievents)
63 | * Tests are mirrored on [wpt.live/uievents/](https://wpt.live/uievents/)
64 |
65 | ## Recommendations
66 |
67 | If you enjoyed this spec, you might be interested in these other specs from the same publisher:
68 |
69 | * UI Events KeyboardEvent code Values: [GitHub project](https://github.com/w3c/uievents-code/), [Link to spec](https://w3c.github.io/uievents-code/)
70 | * UI Events KeyboardEvent key Values: [GitHub project](https://github.com/w3c/uievents-key/), [Link to spec](https://w3c.github.io/uievents-key/)
71 |
--------------------------------------------------------------------------------
/build.py:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env python
2 |
3 | """Script to build the Bikeshed (.bs) files for the UI Events spec."""
4 |
5 | from __future__ import print_function
6 |
7 | import os.path
8 | import re
9 | import subprocess
10 | import sys
11 |
12 | DEBUG = False
13 |
14 | # This Parser processes the base *.txt files in the section/ directory to produce a set
15 | # of output *.bs files that can be used as input to Bikeshed to create the final .html
16 | # file.
17 | # This pre-processing marks up the Key and Code values (with appropriate links) and
18 | # generates HTML tables from the ASCII markup.
19 | class Parser():
20 | """Pre-bikeshed parser for uievents spec."""
21 |
22 | TABLE_TYPE_EVENT_SEQUENCE = 'event-sequence'
23 | TABLE_TYPE_EVENT_DEFINITION = 'event-definition'
24 |
25 | def __init__(self):
26 | self.curr_src = ''
27 | self.curr_dst = ''
28 |
29 | self.in_table = False
30 | self.table_type = ''
31 | self.table_header_data = []
32 | self.table_column_format = []
33 | self.table_row_data = []
34 | self.is_header_row = False
35 |
36 | self.id = '0'
37 | self.event = 'evy'
38 | self.desc = 'desc'
39 |
40 | def error(self, msg):
41 | print(self.curr_src, self.line)
42 | print('Error: %s' % (msg))
43 | sys.exit(1)
44 |
45 | def event_type(self, type):
46 | if type == '' or type == '...':
47 | return type
48 | return '' + type + ''
49 |
50 | def table_row(self):
51 | # Don't print header row for event-definition.
52 | if self.is_header_row and self.table_type == Parser.TABLE_TYPE_EVENT_DEFINITION:
53 | return ''
54 |
55 | if self.is_header_row:
56 | self.table_row_data = self.table_header_data
57 |
58 | if len(self.table_row_data) == 0:
59 | return ''
60 | if self.is_header_row:
61 | row = '
'
62 | else:
63 | row = '
'
64 | for i in range(0, len(self.table_row_data)):
65 | data = self.table_row_data[i]
66 | colname = self.table_header_data[i]
67 | align = self.table_column_format[i]
68 | style = ''
69 | if align == 'right':
70 | style = ' style="text-align:right"'
71 | elif align == 'center':
72 | style = ' style="text-align:center"'
73 | pre = '' % style
74 | post = ''
75 | if self.is_header_row or colname == '%':
76 | pre = '' % style
77 | post = ''
78 | if colname == '#':
79 | pre = '
' % style
80 | if self.is_header_row:
81 | data = ''
82 | if not self.is_header_row and data != '':
83 | if colname == 'Event Type':
84 | data = self.event_type(data)
85 | if colname == 'DOM Interface':
86 | data = '{{' + data + '}}'
87 | row += pre + self.process_text(data) + post
88 | if self.is_header_row:
89 | row += '
\n'
90 | else:
91 | row += '\n'
92 | return row
93 |
94 | def process_text(self, desc):
95 | m = re.match(r'^(.*)EVENT{(.+?)}(.*)$', desc)
96 | if m:
97 | pre = self.process_text(m.group(1))
98 | name = m.group(2)
99 | post = self.process_text(m.group(3))
100 | desc = pre + self.event_type(name) + post
101 |
102 | m = re.match(r'^(.*)CODE{(.*?)}(.*)$', desc)
103 | if m:
104 | pre = self.process_text(m.group(1))
105 | name = m.group(2)
106 | post = self.process_text(m.group(3))
107 | desc = '%s"%s"%s' % (pre, name, name, post)
108 |
109 | m = re.match(r'^(.*)KEY{(.+?)}(.*)$', desc)
110 | if m:
111 | pre = self.process_text(m.group(1))
112 | name = m.group(2)
113 | post = self.process_text(m.group(3))
114 | desc = '%s"%s"%s' % (pre, name, name, post)
115 |
116 | m = re.match(r'^(.*)KEY_NOLINK{(.+?)}(.*)$', desc)
117 | if m:
118 | pre = self.process_text(m.group(1))
119 | name = m.group(2)
120 | post = self.process_text(m.group(3))
121 | desc = '%s"%s"%s' % (pre, name, post)
122 |
123 | m = re.match(r'^(.*)KEYCAP{(.+?)}(.*)$', desc)
124 | if m:
125 | pre = self.process_text(m.group(1))
126 | name = m.group(2)
127 | post = self.process_text(m.group(3))
128 | desc = pre + '' + name + '' + post
129 |
130 | m = re.match(r'^(.*)GLYPH{(.*?)}(.*)$', desc)
131 | if m:
132 | pre = self.process_text(m.group(1))
133 | name = m.group(2)
134 | post = self.process_text(m.group(3))
135 | desc = pre + '"' + name + '"' + post
136 |
137 | m = re.match(r'^(.*)UNI{(.+?)}(.*)$', desc)
138 | if m:
139 | pre = self.process_text(m.group(1))
140 | name = m.group(2)
141 | post = self.process_text(m.group(3))
142 | if name[0:2] != 'U+':
143 | self.error('Invalid Unicode value (expected U+xxxx): %s\n' % name)
144 | desc = pre + '' + name + '' + post
145 |
146 | return desc
147 |
148 | def process_line(self, line):
149 | if self.in_table:
150 | # Header rows begin with '=|'
151 | m = re.match(r'^\s*\=\|(.*)\|$', line)
152 | if m:
153 | self.table_header_data = [x.strip() for x in m.group(1).split('|')]
154 | self.is_header_row = True
155 | return ''
156 |
157 | # New data rows begin with '+|'
158 | m = re.match(r'^\s*\+\|(.*)\|$', line)
159 | if m:
160 | result = self.table_row()
161 | self.table_row_data = [x.strip() for x in m.group(1).split('|')]
162 | self.is_header_row = False
163 | return result
164 |
165 | # Tables end with: '++--'
166 | m = re.match(r'^\s*\+\+--', line)
167 | if m:
168 | self.in_table = False
169 | return self.table_row() + '\n'
170 |
171 | # Separator lines begin with ' +' and end with '+'
172 | # They may only contain '-', '+' and 'o'.
173 | m = re.match(r'^\s* \+([\-\+o]+)\+', line)
174 | if m:
175 | # Separator lines may contain column formatting info.
176 | num_columns = len(self.table_header_data)
177 | format_data = [x.strip() for x in m.group(1).split('+')]
178 | if len(format_data) != num_columns:
179 | self.error('Unexpected number of columns (%d) in row (expected %d):\n%s'
180 | % (len(format_data), num_columns, line))
181 | for i in range(0, len(self.table_header_data)):
182 | align = 'left'
183 | if len(format_data[i]) != 0:
184 | if format_data[i][0] == 'o':
185 | align = 'left'
186 | elif format_data[i][-1] == 'o':
187 | align = 'right'
188 | elif 'o' in format_data[i]:
189 | align = 'center'
190 | self.table_column_format.append(align)
191 | return ''
192 |
193 | # Row continued from previous line: ' |'
194 | m = re.match(r'^\s*\|(.*)\|', line)
195 | if m:
196 | num_columns = len(self.table_header_data)
197 | extra_data = [x.strip() for x in m.group(1).split('|')]
198 | if len(extra_data) != num_columns:
199 | self.error('Unexpected number of columns (%d) in row (expected %d):\n%s'
200 | % (len(extra_data), num_columns, line))
201 | for i in range(0, len(self.table_header_data)):
202 | if len(extra_data[i]) != 0:
203 | if self.is_header_row:
204 | self.table_header_data[i] += ' ' + extra_data[i]
205 | else:
206 | self.table_row_data[i] += ' ' + extra_data[i]
207 | return ''
208 |
209 | self.error('Expected table line: ' + line)
210 | return('')
211 |
212 | # Tables begin with: ++---+----+-------+
213 | m = re.match(r'^\s*\+\+--[\-\+]*\+(?P [\-a-z]+)?$', line)
214 | if m:
215 | table_class = m.group('class')
216 | if table_class == None:
217 | table_class = 'event-sequence-table'
218 | self.table_type = Parser.TABLE_TYPE_EVENT_SEQUENCE
219 | else:
220 | table_class = table_class[1:]
221 | self.table_type = Parser.TABLE_TYPE_EVENT_DEFINITION
222 | self.in_table = True
223 | #self.table_type = Parser.TABLE_TYPE_EVENT_SEQUENCE
224 | self.table_header_data = []
225 | self.table_column_format = []
226 | self.table_row_data = []
227 | return '
184 |
--------------------------------------------------------------------------------
/proposals/d3e-keyflow.svg:
--------------------------------------------------------------------------------
1 |
269 |
--------------------------------------------------------------------------------
/proposals/dblclick.txt:
--------------------------------------------------------------------------------
1 | Type dblclick
2 | Namespace None
3 | Interface MouseEvent
4 | Cancelable Yes
5 | Bubbles Yes
6 | Target Element
7 |
8 | Context Info is the same as for the click event the dblclick event is dispatched
9 | after, including UIEvent.detail taken in account platform conventions.
10 |
11 | dblclick is dispatched after the click event. It is not dispatched as default
12 | action of the click event though, cancelling the click event does not cancel the
13 | dblclick event.
--------------------------------------------------------------------------------
/proposals/mousewheel.txt:
--------------------------------------------------------------------------------
1 | When "mouse wheeling" occurs, the implementation must dispatch a
2 | mouseomniwheel event implementing the following interface:
3 |
4 | interface MouseOmniWheelEvent : MouseEvent {
5 | readonly attribute long wheelDeltaX;
6 | readonly attribute long wheelDeltaY;
7 | readonly attribute long wheelDeltaZ;
8 | void initMouseOmniWheelEventNS(in DOMString namespaceURI,
9 | in DOMString typeArg,
10 | in boolean canBubbleArg,
11 | in boolean cancelableArg,
12 | in views::AbstractView viewArg,
13 | in long detailArg,
14 | in long screenXArg,
15 | in long screenYArg,
16 | in long clientXArg,
17 | in long clientYArg,
18 | in unsigned short buttonArg,
19 | in EventTarget relatedTargetArg,
20 | in DOMString modifiersList,
21 | in long wheelDeltaX,
22 | in long wheelDeltaY,
23 | in long wheelDeltaZ);
24 | };
25 |
26 | wheelDeltaX is a number indicating the horizontal distance (positive means
27 | rotated to the right, negative means rotated to the left).
28 |
29 | wheelDeltaY is a number indicating the vertical distance (positive means rotated
30 | away from user or to the right, negative means rotated towards user or to the
31 | left).
32 |
33 | wheelDeltaZ, included for future extensibility, is a number indicating the
34 | distance along a third unspecified axis (positive means rotated away from the
35 | user, means rotated towards user). At the present time, implementors may use
36 | whatever modality is best suited to the task, such as the the use of the wheel
37 | in conjunction with a control key.
38 |
39 | The default value of wheelDeltaX, wheelDeltaY and wheelDeltaZ is 0.
40 | UIEvent.detail must always be 0.
41 |
42 | This event includes both scroll deltas. The default action of this event is to
43 | dispatch a mousewheel event if the y delta is non-zero. Besides
44 | that, its default action is to do whatever platform conventions suggest for the
45 | wheeling behavior.
46 |
47 | The mousewheel event implements the following interface:
48 |
49 | interface MouseWheelEvent : MouseEvent {
50 | readonly attribute long wheelDelta;
51 | void initMouseWheelEventNS(in DOMString namespaceURI,
52 | in DOMString typeArg,
53 | in boolean canBubbleArg,
54 | in boolean cancelableArg,
55 | in views::AbstractView viewArg,
56 | in long detailArg,
57 | in long screenXArg,
58 | in long screenYArg,
59 | in long clientXArg,
60 | in long clientYArg,
61 | in unsigned short buttonArg,
62 | in EventTarget relatedTargetArg,
63 | in DOMString modifiersList,
64 | in long wheelDelta);
65 | };
66 |
67 | If the mousewheel event is cancelled, only the default action for
68 | vertical wheeling is cancelled.
69 |
70 | wheelDelta
71 | A number indicating the distance, measured as the number of "clicks" the wheel has been rotated. A positive value indicates that the wheel has been rotated away from the user (or in a right-hand manner on horizontally aligned devices) and a negative value indicates that the wheel has been rotated towards the user (or in a left-hand manner on horizontally aligned devices). The default value of the wheelDelta attribute is 0.
72 |
73 | A "click" is defined to be a unit of rotation. On some devices this is a finite physical step. On devices with smooth rotation, a "click" becomes the smallest reported amount of rotation.
74 |
75 |
76 | XXX: What about UIEvent.detail?
77 |
78 | For both mouseomniwheel and mousewheel,
79 | MouseEvent.relatedNode must indicate the element over which the
80 | pointer is located, or null if there is no such element (in the
81 | case where the device does not have a pointer, but does have a wheel).
82 |
83 |
84 |
--------------------------------------------------------------------------------
/sections/acknowledgements.txt:
--------------------------------------------------------------------------------
1 |
2 |
Acknowledgements
3 |
4 |
5 | Many people contributed to the DOM specifications (Level 1, 2 or 3),
6 | including participants of the DOM Working Group, the DOM Interest Group,
7 | the WebAPI Working Group, and the WebApps Working Group.
8 | We especially thank the following:
9 |
10 | Andrew Watson (Object Management Group),
11 | Andy Heninger (IBM),
12 | Angel Diaz (IBM),
13 | Anne van Kesteren (Opera Software),
14 | Arnaud Le Hors (W3C and IBM),
15 | Arun Ranganathan (AOL),
16 | Ashok Malhotra (IBM and Microsoft),
17 | Ben Chang (Oracle),
18 | Bill Shea (Merrill Lynch),
19 | Bill Smith (Sun),
20 | Björn Höhrmann,
21 | Bob Sutor (IBM),
22 | Charles McCathie-Nevile (Opera Software, Co-Chair),
23 | Chris Lovett (Microsoft),
24 | Chris Wilson (Microsoft),
25 | Christophe Jolif (ILOG),
26 | David Brownell (Sun),
27 | David Ezell (Hewlett-Packard Company),
28 | David Singer (IBM),
29 | Dean Jackson (W3C, W3C Team Contact),
30 | Dimitris Dimitriadis (Improve AB and invited expert),
31 | Don Park (invited),
32 | Doug Schepers (Vectoreal),
33 | Elena Litani (IBM),
34 | Eric Vasilik (Microsoft),
35 | Gavin Nicol (INSO),
36 | Gorm Haug Eriksen (Opera Software),
37 | Ian Davis (Talis Information Limited),
38 | Ian Hickson (Google),
39 | Ian Jacobs (W3C),
40 | James Clark (invited),
41 | James Davidson (Sun),
42 | Jared Sorensen (Novell),
43 | Jeroen van Rotterdam (X-Hive Corporation),
44 | Joe Kesselman (IBM),
45 | Joe Lapp (webMethods),
46 | Joe Marini (Macromedia),
47 | John Robinson (AOL),
48 | Johnny Stenback (Netscape/AOL),
49 | Jon Ferraiolo (Adobe),
50 | Jonas Sicking (Mozilla Foundation),
51 | Jonathan Marsh (Microsoft),
52 | Jonathan Robie (Texcel Research and Software AG),
53 | Kim Adamson-Sharpe (SoftQuad Software Inc.),
54 | Lauren Wood (SoftQuad Software Inc., former Chair),
55 | Laurence Cable (Sun),
56 | Luca Mascaro (HTML Writers Guild),
57 | Maciej Stachowiak (Apple Computer),
58 | Marc Hadley (Sun Microsystems),
59 | Mark Davis (IBM),
60 | Mark Scardina (Oracle),
61 | Martin Dürst (W3C),
62 | Mary Brady (NIST),
63 | Michael Shenfield (Research In Motion),
64 | Mick Goulish (Software AG),
65 | Mike Champion (Arbortext and Software AG),
66 | Miles Sabin (Cromwell Media),
67 | Patti Lutsky (Arbortext),
68 | Paul Grosso (Arbortext),
69 | Peter Sharpe (SoftQuad Software Inc.),
70 | Phil Karlton (Netscape),
71 | Philippe Le Hégaret (W3C, W3C Team Contact and former Chair),
72 | Ramesh Lekshmynarayanan (Merrill Lynch),
73 | Ray Whitmer (iMall, Excite@Home, and Netscape/AOL, Chair),
74 | Rezaur Rahman (Intel),
75 | Rich Rollman (Microsoft),
76 | Rick Gessner (Netscape),
77 | Rick Jelliffe (invited),
78 | Rob Relyea (Microsoft),
79 | Robin Berjon (Expway, Co-Chair),
80 | Scott Hayman (Research In Motion),
81 | Scott Isaacs (Microsoft),
82 | Sharon Adler (INSO),
83 | Stéphane Sire (IntuiLab),
84 | Steve Byrne (JavaSoft),
85 | Tim Bray (invited),
86 | Tim Yu (Oracle),
87 | Tom Pixley (Netscape/AOL),
88 | T.V. Raman (Google).
89 | Vidur Apparao (Netscape) and
90 | Vinod Anupam (Lucent).
91 |
92 | Former editors:
93 | Tom Pixley (Netscape Communications Corporation) until July 2002;
94 | Philippe Le Hégaret (W3C) until November 2003;
95 | Björn Höhrmann (Invited Expert) until January 2008;
96 | and Jacob Rossi (Microsoft) from March 2011 to October 2011.
97 |
98 | Contributors:
99 | In the WebApps Working Group, the following people made substantial
100 | material contributions in the process of refining and revising this
101 | specification:
102 | Bob Lund (Cable Laboratories),
103 | Cameron McCormack (Invited Expert / Mozilla),
104 | Daniel Danilatos (Google),
105 | Gary Kacmarcik (Google),
106 | Glenn Adams (Samsung),
107 | Hallvord R. M. Steen (Opera),
108 | Hironori Bono (Google),
109 | Mark Vickers (Comcast),
110 | Masayuki Nakano (Mozilla),
111 | Olli Pettay (Mozilla),
112 | Takayoshi Kochi (Google) and
113 | Travis Leithead (Microsoft).
114 |
115 | Glossary contributors:
116 | Arnaud Le Hors (W3C) and
117 | Robert S. Sutor (IBM Research).
118 |
119 | Test suite contributors:
120 | Carmelo Montanez (NIST),
121 | Fred Drake,
122 | Mary Brady (NIST),
123 | Neil Delima (IBM),
124 | Rick Rivello (NIST),
125 | Robert Clary (Netscape),
126 | with a special mention to Curt Arnold.
127 |
128 | Thanks to all those who have helped to improve this specification by
129 | sending suggestions and corrections (please, keep bugging us with your
130 | issues!), or writing informative books or Web sites:
131 | Al Gilman,
132 | Alex Russell,
133 | Alexander J. Vincent,
134 | Alexey Proskuryakov,
135 | Arkadiusz Michalski,
136 | Brad Pettit,
137 | Cameron McCormack,
138 | Chris Rebert,
139 | Curt Arnold,
140 | David Flanagan,
141 | Dylan Schiemann,
142 | Erik Arvidsson,
143 | Garrett Smith,
144 | Giuseppe Pascale,
145 | James Su,
146 | Jan Goyvaerts (regular-expressions.info),
147 | Jorge Chamorro,
148 | Kazuyuki Ashimura,
149 | Ken Rehor,
150 | Magnus Kristiansen,
151 | Martijn Wargers,
152 | Martin Dürst,
153 | Michael B. Allen,
154 | Mike Taylor,
155 | Misha Wolf,
156 | Ojan Vafai,
157 | Oliver Hunt,
158 | Paul Irish,
159 | Peter-Paul Koch,
160 | Richard Ishida,
161 | Sean Hogan,
162 | Sergey Ilinsky,
163 | Sigurd Lerstad,
164 | Steven Pemberton,
165 | Tony Chang,
166 | William Edney and
167 | Øistein E. Andersen.
168 |
169 |
170 |
--------------------------------------------------------------------------------
/sections/conventions.txt:
--------------------------------------------------------------------------------
1 |
2 |
Stylistic Conventions
3 |
4 |
5 | This specification follows the
6 | Proposed W3C Specification Conventions,
7 | with the following supplemental additions:
8 |
9 | * The key cap printed on a key is shown as
10 | KEYCAP{↓}, KEYCAP{=} or KEYCAP{Q}. This is used to refer to a
11 | key from the user's perspective without regard for the
12 | {{KeyboardEvent/key}} and {{KeyboardEvent/code}} values in the
13 | generated {{KeyboardEvent}}.
14 |
15 | * Glyphs representing character are shown as: GLYPH{𣧂}.
16 |
17 | * Unicode character encodings are shown as: UNI{U+003d}.
18 |
19 | * Names of key values generated by a key press (i.e., the value of
20 | {{KeyboardEvent}}.{{KeyboardEvent/key}}) are shown as:
21 | KEY{ArrowDown}, KEY_NOLINK{=}, KEY_NOLINK{q} or KEY_NOLINK{Q}.
22 |
23 | * Names of key codes associated with the physical keys (i.e., the
24 | value of {{KeyboardEvent}}.{{KeyboardEvent/code}}) are shown as:
25 | CODE{ArrowDown}, CODE{Equal} or CODE{KeyQ}.
26 |
27 |
28 | In addition, certain terms are used in this specification with particular
29 | meanings. The term implementation applies to a browser, content
30 | authoring tool, or other user agent that implements this specification,
31 | while a content author is a person who writes script or code that takes
32 | advantage of the interfaces, methods, attributes, events, and other features
33 | described in this specification in order to make Web applications, and a user is
34 | the person who uses those Web applications in an implementation.
35 |
36 | And finally:
37 |
38 |
This is a note.
39 |
40 |
41 |
42 |
This is an open issue.
43 |
44 |
This is a warning.
45 |
46 |
47 | interface Example {
48 | // This is an IDL definition.
49 | };
50 |
3 |
4 | Input events are sent as notifications whenever the DOM is being updated (or about
5 | to be updated) as a direct result of a user action (e.g., keyboard input in an editable
6 | region, deleting or formatting text, ...).
7 |
8 |
27 | data holds the value of the characters generated by
28 | an input method. This MAY be a single Unicode character or a
29 | non-empty sequence of Unicode characters [[Unicode]]. Characters
30 | SHOULD be normalized as defined by the Unicode normalization
31 | form NFC, defined in [[UAX15]].
32 | This attribute MAY contain the empty string.
33 |
34 | The un-initialized value of this attribute MUST be
35 | null.
36 |
37 |
38 |
isComposing
39 |
40 | true if the input event occurs as part of a
41 | composition session, i.e., after a EVENT{compositionstart} event
42 | and before the corresponding EVENT{compositionend} event.
43 |
44 | The un-initialized value of this attribute MUST be
45 | false.
46 |
47 |
48 |
inputType
49 |
50 | inputType contains a string that identifies the type
51 | of input associated with the event.
52 |
53 | For a list of valid values for this attribute, refer to the
54 | [[Input-Events]] specification.
55 |
56 | The un-initialized value of this attribute MUST be
57 | the empty string "".
58 |
74 | Initializes the data attribute of the InputEvent object.
75 |
76 |
77 |
isComposing
78 |
79 | Initializes the isComposing attribute of the InputEvent object.
80 |
81 |
82 |
inputType
83 |
84 | Initializes the inputType attribute of the InputEvent object.
85 |
86 |
87 |
88 |
Input Event Order
89 |
90 | The input events defined in this specification MUST occur in a set order
91 | relative to one another.
92 |
93 | ++---+-------------+---------------------------------------------------+
94 | =| # | Event Type | Notes |
95 | +---+-------------+---------------------------------------------------+
96 | +| 1 | beforeinput | |
97 | +| | | DOM element is updated |
98 | +| 2 | input | |
99 | ++---+-------------+---------------------------------------------------+
100 |
101 |
Input Event Types
102 |
103 |
beforeinput
104 |
105 | ++------------------+--------------------------------------------------------------------------------------+ event-definition
106 | =| % | |
107 | +------------------+--------------------------------------------------------------------------------------+
108 | +| Type | beforeinput |
109 | +| Interface | {{InputEvent}} |
110 | +| Sync / Async | Sync |
111 | +| Bubbles | Yes |
112 | +| Trusted Targets | Element (specifically: control types such as |
113 | | | HTMLInputElement, etc.) or any Element with |
114 | | | contenteditable attribute enabled |
115 | +| Cancelable | Yes |
116 | +| Composed | Yes |
117 | +| Default action | Update the DOM element |
118 | +| Context |
|
119 | | (trusted events) |
{{Event}}.{{Event/target}} : event target that is about to be updated
{{InputEvent}}.{{InputEvent/data}} : the string containing the data that will |
123 | | | be added to the element, which MAY be null if the content will |
124 | | | be deleted
|
125 | | |
{{InputEvent}}.{{InputEvent/isComposing}} : true if this event is |
126 | | | dispatched during a dead key sequence or while an |
127 | | | input method editor is active (such that |
128 | | | composition events are being dispatched);|
129 | | | false otherwise.
|
130 | | |
|
131 | ++------------------+--------------------------------------------------------------------------------------+
132 |
133 | A user agent MUST dispatch this event when the DOM is about
134 | to be updated.
135 |
136 |
{{InputEvent}}.{{InputEvent/data}} : the string containing the data that has |
156 | | | been added to the element, which MAY be the empty string if the content |
157 | | | has been deleted
|
158 | | |
{{InputEvent}}.{{InputEvent/isComposing}} : true if this event is |
159 | | | dispatched during a dead key sequence or while an |
160 | | | input method editor is active (such that |
161 | | | composition events are being dispatched);|
162 | | | false otherwise.
|
163 | | |
|
164 | ++------------------+--------------------------------------------------------------------------------------+
165 |
166 | A user agent MUST dispatch this event immediately after the
167 | DOM has been updated.
168 |
169 |
170 |
171 |
--------------------------------------------------------------------------------
/sections/extending-events.txt:
--------------------------------------------------------------------------------
1 |
2 |
Extending Events
3 |
4 |
5 | This section is non-normative
6 |
7 |
Introduction
8 |
9 | This specification defines several interfaces and many events, however, this
10 | is not an exhaustive set of events for all purposes. To allow content
11 | authors and implementers to add desired functionality, this specification
12 | provides two mechanisms for extend this set of interfaces and events without
13 | creating conflicts: custom
14 | events and implementation-specific
16 | extensions.
17 |
18 |
Custom Events
19 |
20 | A script author MAY wish to define an application in terms of functional
21 | components, with event types that are meaningful to the application
22 | architecture. The content author can use the {{CustomEvent}} interface to
23 | create their own events appropriate to the level of abstraction they are
24 | using.
25 |
26 |
27 | A content author might have created an application which features a
28 | dynamically generated bar chart. This bar chart is meant to be updated every
29 | 5 minutes, or when a feed shows new information, or when the user refreshes
30 | it manually by clicking a button. There are several handlers that have to be
31 | called when the chart needs to be updated: the application has to fetch the
32 | most recent data, show an icon to the user that the event is being updated,
33 | and rebuild the chart. To manage this, the content author can choose to
34 | create a custom updateChart event, which is fired whenever one of the
35 | trigger conditions is met:
36 |
37 |
46 |
47 | While a new event is being designed and prototyped, or when an event is
48 | intended for implementation-specific functionality, it is desirable to
49 | distinguish it from standardized events. Implementors SHOULD prefix event
50 | types specific to their implementations with a short string to distinguish
51 | it from the same event in other implementations and from standardized
52 | events. This is similar to the
53 | vendor-specific keyword prefixes
54 | in CSS, though without the dashes ("-") used in CSS, since that
55 | can cause problems when used as an attribute name in Javascript.
56 |
57 |
58 | A particular browser vendor, FooCorp, might wish to introduce a
59 | new event, jump. This vendor implements
60 | fooJump in their browser, using their
61 | vendor-specific prefix: "foo". Early adopters start
62 | experimenting with the event, using
63 | someElement.addEventListener("fooJump", doJump, false ),
64 | and provide feedback to FooCorp, who change the behavior of fooJump accordingly.
66 |
67 | After some time, another vendor, BarOrg, decides they also want
68 | the functionality, but implement it slightly differently, so they use
69 | their own vendor-specific prefix, "bar" in their event type
70 | name: barJump. Content authors
71 | experimenting with this version of the jump event type register events with BarOrg's
73 | event type name. Content authors who wish to write code that accounts
74 | for both browsers can either register each event type separately with
75 | specific handlers, or use the same handler and switch on the name of the
76 | event type. Thus, early experiments in different codebases do not
77 | conflict, and the early adopter is able to write easily-maintained code
78 | for multiple implementations.
79 |
80 | Eventually, as the feature matures, the behavior of both browsers
81 | stabilizes and might converge due to content author and user feedback or
82 | through formal standardization. As this stabilization occurs, and risk
83 | of conflicts decrease, content authors can remove the forked code, and
84 | use the jump event type name (even before
85 | it is formally standardized) using the same event handler and the more
86 | generic registration method someElement.addEventListener( "jump",
87 | doJump, false).
88 |
89 |
90 |
Known Implementation-Specific Prefixes
91 |
92 | At the time of writing, the following event-type name prefixes are known to exist:
93 |
94 | ++---------------------+------------+-----------------------+
95 | =| Prefix | Web Engine | Organization |
96 | +---------------------+------------+-----------------------+
97 | +| moz, | Gecko | Mozilla |
98 | | Moz | | |
99 | +| ms, | Trident | Microsoft |
100 | | MS | | |
101 | +| o, | Presto | Opera Software |
102 | | O | | |
103 | +| webkit | WebKit | Apple, Google, others |
104 | ++---------------------+------------+-----------------------+
105 |
106 |
107 |
--------------------------------------------------------------------------------
/sections/external-algorithms.txt:
--------------------------------------------------------------------------------
1 |
2 |
External Algorithms
3 |
4 | This sections contains algorithms that are required by this specification, but are
5 | more properly hosted by other specifications.
6 |
7 | The intent is that this sections serve as a temporary home for these definitions,
8 | and they should eventually be moved into a more appropriate home so this entire
9 | section can be deleted.
10 |
11 |
Core DOM Algorithms
12 |
13 |
14 | The following algorithms should be moved... somewhere.
15 |
16 |
17 |
18 |
hit test
19 |
20 | : Input
21 | :: |pos|, the x,y coordinates relative to the viewport
22 |
23 | : Output
24 | :: The frontmost DOM element at |pos|
25 |
26 |
27 | To account for
28 | inert or
29 | disabled
30 | elements. this should call elementsFromPoint and reject
31 | invalid elements
32 |
40 |
41 | : Input
42 | :: |element|, the starting element
43 |
44 | : Output
45 | :: The list of ancestor elements for the given element
46 |
47 | 1. Let |path| = A list that contains |element|
48 |
49 |
50 | This needs a proper definition to add ancestors to |path|.
51 |
52 |
53 | 1. Return |path|
54 |
55 |
56 |
57 |
PointerLock Algorithms
58 |
59 |
60 | The following algorithm should be moved into the [[PointerLock]] spec.
61 |
62 |
63 |
Global State for PointerLock
64 |
65 |
Window-Level State
66 |
67 | The UA must maintain the following values that are shared for the Window.
68 |
69 | A last mouse move value (initially undefined) that records the position of the
70 | last mousemove event.
71 |
72 |
88 |
89 | : Input
90 | :: |event|, a {{MouseEvent}}
91 |
92 | : Output
93 | :: None
94 |
95 | 1. If |event|.{{Event/type}} is not "mousemove", then exit
96 |
97 | 1. If last mouse move is not defined, then
98 | 1. Set |event|.{{MouseEvent/movementX}} = 0
99 | 1. Set |event|.{{MouseEvent/movementY}} = 0
100 | 1. Otherwise,
101 | 1. Set |event|.{{MouseEvent/movementX}} = |event|.{{MouseEvent/screenX}} - last mouse move's x-coordinate
102 | 1. Set |event|.{{MouseEvent/movementY}} = |event|.{{MouseEvent/screenX}} - last mouse move's y-coordinate
103 |
104 | 1. Set last mouse move = ( |event|.{{MouseEvent/screenX}}, |event|.{{MouseEvent/screenY}} )
105 |
106 |
107 |
108 |
PointerEvent Algorithms
109 |
110 |
111 | The following algorithms should be moved into the [[PointerEvents3]] spec.
112 |
113 |
114 |
115 |
initialize a PointerEvent
116 |
117 | : Input
118 | :: |event|, the {{PointerEvent}} to initialize
119 | :: |eventType|, a DOMString containing the event type
120 | :: |eventTarget|, the {{EventTarget}} of the event
121 |
122 | : Output
123 | :: None
124 |
125 | 1. Initialize a MouseEvent with |event|, |eventType| and |eventTarget|
126 |
127 |
128 | TODO - initialize the pointerevent attributes
129 |
130 |
131 |
132 |
133 |
134 |
create a PointerEvent
135 |
136 | : Input
137 | :: |eventType|, a DOMString containing the event type
138 | :: |eventTarget|, the {{EventTarget}} of the event
139 |
140 | : Output
141 | :: None
142 |
143 | 1. Let |event| = the result of
144 | creating a new event using {{PointerEvent}}
145 | 1. Initialize a PointerEvent with |event|, |eventType| and |eventTarget|
146 | 1. Return |event|
147 |
148 |
149 |
150 |
151 |
create PointerEvent from MouseEvent
152 |
153 | : Input
154 | :: |eventType|, a DOMString containing the event type
155 | :: |mouseevent|, the corresponding {{MouseEvent}}
156 |
157 | : Output
158 | :: None
159 |
160 | 1. Let |event| = the result of
161 | creating a new event using {{PointerEvent}}
162 |
163 | 1. Let |target| = |mouseevent|.{{target}}
164 |
165 | 1. Initialize a PointerEvent with |event|, |eventType| and |target|
166 |
167 | 1. Copy MouseEvent attributes from |mouseevent| into |event|
168 |
169 | 1. Return |event|
170 |
171 |
172 |
173 |
174 |
maybe send pointerout event
175 |
176 | : Input
177 | :: |mouseout|, the corresponding mouseout {{MouseEvent}}
178 |
179 | : Output
180 | :: None
181 |
182 | 1. Let |pointerout| = create PointerEvent from MouseEvent with "pointerout" and |mouseout|
183 |
184 | 1. Set pointerevent attributes
185 |
186 |
187 | TODO
188 |
189 |
190 | 1. Let |target| = |mouseout|.{{target}}
191 | 1. dispatch |pointerout| at |target|
192 |
193 |
194 |
195 |
196 |
maybe send pointerleave event
197 |
198 | : Input
199 | :: |mouseout|, the corresponding mouseout {{MouseEvent}}
200 |
201 | : Output
202 | :: None
203 |
204 | 1. Let |pointerout| = create PointerEvent from MouseEvent with "pointerout" and |mouseout|
205 |
206 | 1. Set pointerevent attributes
207 |
208 |
209 | TODO
210 |
211 |
212 | 1. Let |target| = |mouseout|.{{target}}
213 | 1. dispatch |pointerout| at |target|
214 |
215 |
216 |
217 |
218 |
maybe send pointerover event
219 |
220 | : Input
221 | :: |mouseout|, the corresponding mouseout {{MouseEvent}}
222 |
223 | : Output
224 | :: None
225 |
226 | 1. Let |pointerout| = create PointerEvent from MouseEvent with "pointerout" and |mouseout|
227 |
228 | 1. Set pointerevent attributes
229 |
230 |
231 | TODO
232 |
233 |
234 | 1. Let |target| = |mouseout|.{{target}}
235 | 1. dispatch |pointerout| at |target|
236 |
237 |
238 |
239 |
240 |
maybe send pointerenter event
241 |
242 | : Input
243 | :: |mouseout|, the corresponding mouseout {{MouseEvent}}
244 |
245 | : Output
246 | :: None
247 |
248 | 1. Let |pointerout| = create PointerEvent from MouseEvent with "pointerout" and |mouseout|
249 |
250 | 1. Set pointerevent attributes
251 |
252 |
253 | TODO
254 |
255 |
256 | 1. Let |target| = |mouseout|.{{target}}
257 | 1. dispatch |pointerout| at |target|
258 |
259 |
301 | Unlike mousedown events,
302 | pointerdown
303 | events are not nested when multiple buttons are pressed.
304 | The MouseEvent is passed so that the fields can be copied into the PointerEvent.
305 |
306 |
307 | 1. Let |pointerout| = create PointerEvent from MouseEvent with "pointerout" and |mouseout|
308 |
309 | 1. Set pointerevent attributes
310 |
311 |
312 | TODO
313 |
314 |
315 | 1. Let |target| = |mouseout|.{{target}}
316 | 1. dispatch |pointerout| at |target|
317 |
318 |
330 | Unlike mouseup events,
331 | pointerup
332 | events are not nested when multiple buttons are pressed.
333 | The MouseEvent is passed so that the fields can be copied into the PointerEvent.
334 |
335 |
336 | 1. Let |pointerout| = create PointerEvent from MouseEvent with "pointerout" and |mouseout|
337 |
338 | 1. Set pointerevent attributes
339 |
340 |
341 | TODO
342 |
343 |
344 | 1. Let |target| = |mouseout|.{{target}}
345 | 1. dispatch |pointerout| at |target|
346 |
347 |
3 |
4 | Some of the following term definitions have been borrowed or modified from
5 | similar definitions in other W3C or standards documents. See the links within
6 | the definitions for more information.
7 |
8 |
9 | : activation trigger
10 | :: An event which is defined to initiate an activation behavior.
11 |
12 | : author
13 | :: In the context of this specification, an author, content
14 | author, or script author is a person who writes script or
15 | other executable content that uses the interfaces, events, and event flow
16 | defined in this specification. See [[#conf-authors]] conformance category
17 | for more details.
18 |
19 | : body element
20 | :: In HTML or XHTML documents, the body element represents the contents of the
21 | document. In a well-formed HTML document, the body element is a first
22 | descendant of the root element.
23 |
24 | : character value
25 | :: In the context of key values, a character value is a string representing one
26 | or more Unicode characters, such as a letter or symbol, or a set of letters, each
27 | belonging to the set of valid Unicode character categories.
28 | In this specification, character values are denoted as a unicode string
29 | (e.g., UNI{U+0020}) or a glyph representation of the same code point (e.g.,
30 | GLYPH{ }), and are color coded to help distinguish these two representations.
31 |
32 |
33 | In source code, some key values, such as non-graphic characters, can be
34 | represented using the character escape syntax of the programming language in
35 | use.
36 |
37 |
38 | : dead key
39 | :: A dead key is a key or combination of keys which produces no character by
40 | itself, but which in combination or sequence with another key produces a
41 | modified character, such as a character with diacritical marks (e.g.,
42 | GLYPH{ö}, GLYPH{é}, GLYPH{â}).
43 |
44 | : default action
45 | :: A default action is an OPTIONAL supplementary behavior that an
46 | implementation MUST perform in combination with the dispatch of the event
47 | object. Each event type definition, and each specification, defines the
48 | default action for that event type, if it has one. An instance of an
49 | event MAY have more than one default action under some circumstances,
50 | such as when associated with an activation trigger. A default
51 | action MAY be cancelled through the invocation of the
52 | {{Event/preventDefault()}} method.
53 |
54 | : delta
55 | :: The estimated scroll amount (in pixels, lines, or pages) that the user agent
56 | will scroll or zoom the page in response to the physical movement of an
57 | input device that supports the {{WheelEvent}} interface (such as a mouse
58 | wheel or touch pad). The value of a delta (e.g., the
59 | {{WheelEvent/deltaX}}, {{WheelEvent/deltaY}}, or {{WheelEvent/deltaZ}}
60 | attributes) is to be interpreted in the context of the current
61 | {{WheelEvent/deltaMode}} property. The relationship between the physical
62 | movement of a wheel (or other device) and whether the delta is
63 | positive or negative is environment and device dependent. However, if a user
64 | agent scrolls as the default action then the sign of the delta
65 | is given by a right-hand coordinate system where positive X,Y, and Z axes
66 | are directed towards the right-most edge, bottom-most edge, and farthest
67 | depth (away from the user) of the document, respectively.
68 |
69 | : deprecated
70 | :: Features marked as deprecated are included in the specification as reference
71 | to older implementations or specifications, but are OPTIONAL and
72 | discouraged. Only features which have existing or in-progress replacements
73 | MUST be deprecated in this specification. Implementations which do not
74 | already include support for the feature MAY implement deprecated features
75 | for reasons of backwards compatibility with existing content, but content
76 | authors creating content SHOULD NOT use deprecated features, unless there is
77 | no other way to solve a use case. Other specifications which reference this
78 | specification SHOULD NOT use deprecated features, but SHOULD point instead
79 | to the replacements of which the feature is deprecated in favor. Features
80 | marked as deprecated in this specification are expected to be dropped from
81 | future specifications.
82 |
83 | : empty string
84 | :: The empty string is a value of type DOMString of length
85 | 0, i.e., a string which contains no characters (neither
86 | printing nor control characters).
87 |
88 | : event focus
89 | :: Event focus is a special state of receptivity and concentration on a
90 | particular element or other event target within a document. Each
91 | element has different behavior when focused, depending on its functionality,
92 | such as priming the element for activation (as for a button or hyperlink) or
93 | toggling state (as for a checkbox), receiving text input (as for a text form
94 | field), or copying selected text. For more details, see
95 | [[#events-focusevent-doc-focus]].
96 |
97 | : event focus ring
98 | :: An event focus ring is an ordered set of event focus targets within a
99 | document. A host language MAY define one or more ways to determine
100 | the order of targets, such as document order, a numerical index defined per
101 | focus target, explicit pointers between focus targets, or a hybrid of
102 | different models. Each document MAY contain multiple focus rings, or
103 | conditional focus rings. Typically, for document-order or indexed focus
104 | rings, focus wraps around from the last focus target to the
105 | first.
106 |
107 | : event target
108 | :: The object to which an event is targeted using the event flow.
109 | The event target is the value of the {{Event/target}} attribute.
110 |
111 | : event type
112 | :: An event type is an event object with a particular name and
113 | which defines particular trigger conditions, properties, and other
114 | characteristics which distinguish it from other event types. For example,
115 | the EVENT{click} event type has different characteristics than the
116 | EVENT{mouseover} or EVENT{load} event types. The event type is exposed as
117 | the {{Event/type}} attribute on the event object.
118 | Also loosely referred to as "event", such as the
119 | EVENT{click} event.
120 |
121 | : host language
122 | :: Any language which integrates the features of another language or API
123 | specification, while normatively referencing the origin specification rather
124 | than redefining those features, and extending those features only in ways
125 | defined by the origin specification. An origin specification typically is
126 | only intended to be implemented in the context of one or more host
127 | languages, not as a standalone language. For example, XHTML, HTML, and SVG
128 | are host languages for UI Events, and they integrate and extend the objects
129 | and models defined in this specification.
130 |
131 | : hysteresis
132 | :: A feature of human interface design to accept input values within a certain
133 | range of location or time, in order to improve the user experience. For
134 | example, allowing for small deviation in the time it takes for a user to
135 | double-click a mouse button is temporal hysteresis, and not immediately
136 | closing a nested menu if the user mouses out from the parent window when
137 | transitioning to the child menu is locative hysteresis.
138 |
139 | : IME
140 | : input method editor
141 | :: An input method editor (IME), also known as a front end
142 | processor, is an application that performs the conversion between
143 | keystrokes and ideographs or other characters, usually by user-guided
144 | dictionary lookup, often used in East Asian languages (e.g., Chinese,
145 | Japanese, Korean). An IME MAY also be used for dictionary-based word
146 | completion, such as on mobile devices. See [[#keys-IME]] for treatment of
147 | IMEs in this specification. See also text composition system.
148 |
149 | : key mapping
150 | :: Key mapping is the process of assigning a key value to a particular key, and
151 | is the result of a combination of several factors, including the operating
152 | system and the keyboard layout (e.g., QWERTY, Dvorak, Spanish,
153 | InScript, Chinese, etc.), and after taking into account all modifier
154 | key (KEYCAP{Shift}, KEYCAP{Alt}, et al.) and dead key states.
155 |
156 | : key value
157 | :: A key value is a character value or multi-character string (such as
158 | KEY{Enter}, KEY{Tab}, or KEY{MediaTrackNext}) associated with a key in a
159 | particular state. Every key has a key value, whether or not it has a
160 | character value. This includes control keys, function keys,
161 | modifier keys, dead keys, and any other key. The key value of
162 | any given key at any given time depends upon the key mapping.
163 |
164 | : modifier key
165 | :: A modifier key changes the normal behavior of a key, such as to produce a
166 | character of a different case (as with the KEYCAP{Shift} key), or to alter
167 | what functionality the key triggers (as with the KEYCAP{Fn} or KEYCAP{Alt}
168 | keys). See [[#keys-modifiers]] for more information about modifier keys and
169 | refer to the [=Modifier Keys table=] in [[UIEvents-Key]] for a list
170 | of valid modifier keys.
171 |
172 | : namespace URI
173 | :: A namespace URI is a URI that identifies an XML namespace. This is
174 | called the namespace name in [[XML-Names11]]. See also sections 1.3.2
175 | DOM URIs
176 | and 1.3.3
177 | XML Namespaces
178 | regarding URIs and namespace URIs handling and comparison in the DOM APIs.
179 |
180 | : QWERTY
181 | :: QWERTY (pronounced ˈkwɜrti) is a common keyboard layout,
182 | so named because the first five character keys on the top row of letter keys
183 | are Q, W, E, R, T, and Y. There are many other popular keyboard layouts
184 | (including the Dvorak and Colemak layouts), most designed for localization
185 | or ergonomics.
186 |
187 | : root element
188 | :: The first element node of a document, of which all other elements are
189 | children. The document element.
190 |
191 | : rotation
192 | :: An indication of incremental change on an input device using the
193 | {{WheelEvent}} interface. On some devices this MAY be a literal rotation of
194 | a wheel, while on others, it MAY be movement along a flat surface, or
195 | pressure on a particular button.
196 |
197 | : text composition system
198 | :: A software component that interprets some form of alternate input (such as a
199 | input method editor, a speech processor, or a handwriting recognition
200 | system) and converts it to text.
201 |
202 | : topmost event target
203 | :: The topmost event target MUST be the element highest in the rendering
204 | order which is capable of being an event target. In graphical user
205 | interfaces this is the element under the user's pointing device. A user
206 | interface's hit testing facility is used to determine the target. For
207 | specific details regarding hit testing and stacking order, refer to the
208 | host language.
209 |
210 | : Unicode character categories
211 | :: A subset of the General Category values that are defined for each Unicode
212 | code point. This subset contains all the
213 | Letter (Ll,
214 | Lm,
215 | Lo,
216 | Lt,
217 | Lu),
218 | Number (Nd,
219 | Nl,
220 | No),
221 | Punctuation (Pc,
222 | Pd,
223 | Pe,
224 | Pf,
225 | Pi,
226 | Po,
227 | Ps)
228 | and Symbol (Sc,
229 | Sk,
230 | Sm,
231 | So)
232 | category values.
233 |
234 | : un-initialized value
235 | :: The value of any event attribute (such as {{Event/bubbles}} or
236 | {{Event/currentTarget}}) before the event has been initialized with
237 | {{Event/initEvent()}}. The un-initialized values of an event apply
238 | immediately after a new event has been created using the method
239 | {{Document/createEvent()}}.
240 |
241 |
242 |
--------------------------------------------------------------------------------
/sections/introduction.txt:
--------------------------------------------------------------------------------
1 |
2 |
Introduction
3 |
4 |
5 |
Overview
6 |
7 | UI Events is designed with two main goals. The first goal is the design of
8 | an event system which allows registration of [=event listeners=] and
9 | describes event flow through a tree structure. Additionally, the
10 | specification will provide standard modules of events for user interface
11 | control and document mutation notifications, including defined contextual
12 | information for each of these event modules.
13 |
14 | The second goal of UI Events is to provide a common subset of the current
15 | event systems used in existing browsers. This is intended to foster
16 | interoperability of existing scripts and content. It is not expected that
17 | this goal will be met with full backwards compatibility. However, the
18 | specification attempts to achieve this when possible.
19 |
20 |
21 |
Conformance
22 |
23 | This section is normative.
24 |
25 | Within this specification, the key words MUST, MUST NOT,
26 | REQUIRED, SHALL, SHALL NOT, SHOULD,
27 | SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL
28 | are to be interpreted as described in [[!RFC2119]].
29 |
30 | This specification is to be understood in the context of the DOM Level 3
31 | Core specification [[!DOM-Level-3-Core]] and the general considerations for DOM
32 | implementations apply. For example, handling of namespace URIs is
33 | discussed in
34 | XML Namespaces.
35 | For additional information about
36 | conformance,
37 | please see the DOM Level 3 Core specification [[DOM-Level-3-Core]]. A user
38 | agent is not required to conform to the entirety of another
39 | specification in order to conform to this specification, but it MUST conform
40 | to the specific parts of any other specification which are called out in
41 | this specification (e.g., a conforming UI Events user agent MUST
42 | support the DOMString data type as defined in [[WebIDL]], but
43 | need not support every method or data type defined in [[WebIDL]] in order
44 | to conform to UI Events).
45 |
46 | This specification defines several classes of conformance for different
47 | user agents, specifications, and content authors:
48 |
49 |
50 |
Web browsers and other dynamic or interactive user agents
51 |
52 | A dynamic or interactive user agent, referred to here as a
53 | browser (be it a Web browser, AT (Accessibility Technology)
54 | application, or other similar program), conforms to UI Events if it
55 | supports:
56 |
57 | * the Core module defined in [[DOM-Level-3-Core]]
58 |
59 | * all the interfaces and events with their associated methods,
60 | attributes, and semantics defined in this specification with the
61 | exception of those marked as deprecated (a conforming user
62 | agent MAY implement the deprecated interfaces, events, or APIs for
63 | backwards compatibility, but is not required to do so in order to be
64 | conforming)
65 |
66 | * the complete set of key and code
67 | values defined in [[UIEvents-Key]] and [[UIEvents-Code]] (subject to
68 | platform availability), and
69 |
70 | * all other normative requirements defined in this specification.
71 |
72 | A conforming browser MUST dispatch events appropriate to the
73 | given {{EventTarget}} when the conditions defined for that event
74 | type have been met.
75 |
76 | A browser conforms specifically to UI Events if it implements the
77 | interfaces and related event types specified in this document.
78 |
79 | A conforming browser MUST support scripting, declarative interactivity,
80 | or some other means of detecting and dispatching events in the manner
81 | described by this specification, and MUST support the APIs specified for
82 | that event type.
83 |
84 | In addition to meeting all other conformance criteria, a conforming
85 | browser MAY implement features of this specification marked as
86 | deprecated, for backwards compatibility with existing content,
87 | but such implementation is discouraged.
88 |
89 | A conforming browser MAY also support features not found in this
90 | specification, but which use the interfaces,
91 | events, or other features defined in this specification, and MAY
92 | implement additional interfaces and event types appropriate to
93 | that implementation. Such features can be later standardized in future
94 | specifications.
95 |
96 | A browser which does not conform to all required portions of this
97 | specification MUST NOT claim conformance to UI Events. Such an
98 | implementation which does conform to portions of this specification MAY
99 | claim conformance to those specific portions.
100 |
101 | A conforming browser MUST also be a conforming implementation of
102 | the IDL fragments in this specification, as described in the Web IDL
103 | specification [[WebIDL]].
104 |
105 |
Authoring tools
106 |
107 | A content authoring tool conforms to UI Events if it produces content
108 | which uses the event types, consistent
109 | in a manner as defined in this specification.
110 |
111 | A content authoring tool MUST NOT claim conformance to UI Events for
112 | content it produces which uses features of this specification marked as
113 | deprecated in this specification.
114 |
115 | A conforming content authoring tool SHOULD provide to the content author
116 | a means to use all event types and interfaces appropriate to all
117 | host languages in the content document being produced.
118 |
119 |
Content authors and content
120 |
121 | A content author creates conforming UI Events content if that
122 | content uses the event types
123 | consistent in a manner as defined in this specification.
124 |
125 | A content author SHOULD NOT use features of this specification
126 | marked as deprecated, but SHOULD rely instead upon
127 | replacement mechanisms defined in this specification and elsewhere.
128 |
129 | Conforming content MUST use the semantics of the interfaces and
130 | event types as described in this specification.
131 |
132 |
133 | Content authors are advised to follow best practices as described in
134 | accessibility and
135 | internationalization
136 | guideline specifications.
137 |
138 |
139 |
Specifications and host languages
140 |
141 | A specification or host language conforms to UI Events if it
142 | references and uses the event flow mechanism, interfaces, events,
143 | or other features defined in [[!DOM]], and does not extend
144 | these features in incompatible ways.
145 |
146 | A specification or host language conforms specifically to UI
147 | Events if it references and uses the interfaces and related event
148 | types specified in this document. A conforming specification MAY
149 | define additional interfaces and event types appropriate to that
150 | specification, or MAY extend the UI Events interfaces and event
151 | types in a manner that does not contradict or conflict with the
152 | definitions of those interfaces and event types in this
153 | specification.
154 |
155 | Specifications or host languages which reference UI Events SHOULD
156 | NOT use or recommend features of this specification marked as
157 | deprecated, but SHOULD use or recommend the indicated replacement
158 | for that the feature (if available).
159 |
160 |
161 |
--------------------------------------------------------------------------------
/sections/legacy-event-initializers.txt:
--------------------------------------------------------------------------------
1 |
2 |
Legacy Event Initializers
3 |
4 | This section is normative.
5 | The following features are obsolete and should only be implemented by
6 | user agents that require compatibility with legacy software.
7 |
8 | Early versions of this specification included an initialization method on
9 | the interface (for example initMouseEvent) that required a long
10 | list of parameters that, in most cases, did not fully initialize all
11 | attributes of the event object. Because of this, event interfaces which were
12 | derived from the basic {{Event}} interface required that the initializer of
13 | each of the derived interfaces be called explicitly in order to
14 | fully initialize an event.
15 |
16 |
17 | Initializing all the attributes of a UIEvent requires calls to two
18 | initializer methods: initEvent and
19 | initUIEvent.
20 |
21 |
22 | Due in part to the length of time in the development of this standard, some
23 | implementations MAY have taken a dependency on these (now deprecated)
24 | initializer methods. For completeness, these legacy event initializers are
25 | described in this Appendix.
26 |
27 |
Legacy Event Initializer Interfaces
28 |
29 | This section is informative
30 |
31 | This section documents legacy initializer methods that were introduced
32 | in earlier versions of this specification.
33 |
34 |
114 | Initializes attributes of a {{MouseEvent}} object. This
115 | method has the same behavior as UIEvent.initUIEvent().
116 |
117 |
118 | The initMouseEvent method is deprecated, but
119 | supported for backwards-compatibility with widely-deployed
120 | implementations.
121 |
122 |
123 |
124 |
DOMString typeArg
125 |
126 | Refer to the {{Event/initEvent()}} method for a description of this parameter.
127 |
128 |
129 |
boolean bubblesArg
130 |
131 | Refer to the {{Event/initEvent()}} method for a description of this parameter.
132 |
133 |
134 |
boolean cancelableArg
135 |
136 | Refer to the {{Event/initEvent()}} method for a description of this parameter.
137 |
138 |
139 |
Window? viewArg
140 |
141 | Specifies {{UIEvent/view}}. This value MAY be null.
142 |
143 |
144 |
long detailArg
145 |
146 | Specifies {{UIEvent/detail}}.
147 |
148 |
149 |
long screenXArg
150 |
151 | Specifies {{MouseEvent/screenX}}.
152 |
153 |
154 |
long screenYArg
155 |
156 | Specifies {{MouseEvent/screenY}}.
157 |
158 |
159 |
long clientXArg
160 |
161 | Specifies {{MouseEvent/clientX}}.
162 |
163 |
164 |
long clientYArg
165 |
166 | Specifies {{MouseEvent/clientY}}.
167 |
168 |
169 |
boolean ctrlKeyArg
170 |
171 | Specifies {{MouseEvent/ctrlKey}}.
172 |
173 |
174 |
boolean altKeyArg
175 |
176 | Specifies {{MouseEvent/altKey}}.
177 |
178 |
179 |
boolean shiftKeyArg
180 |
181 | Specifies {{MouseEvent/shiftKey}}.
182 |
183 |
184 |
boolean metaKeyArg
185 |
186 | Specifies {{MouseEvent/metaKey}}.
187 |
188 |
189 |
short buttonArg
190 |
191 | Specifies {{MouseEvent/button}}.
192 |
193 |
194 |
EventTarget? relatedTargetArg
195 |
196 | Specifies {{MouseEvent/relatedTarget}}. This value MAY
197 | be null.
198 |
199 |
200 |
201 |
202 |
203 |
Initializers for interface KeyboardEvent
204 |
205 |
206 | The argument list to this legacy KeyboardEvent initializer does not
207 | include the detailArg (present in other initializers) and
208 | adds the locale argument; it is
209 | necessary to preserve this inconsistency for compatibility with existing
210 | implementations.
211 |
232 | Initializes attributes of a {{KeyboardEvent}} object. This
233 | method has the same behavior as UIEvent.initUIEvent().
234 | The value of {{UIEvent/detail}} remains undefined.
235 |
236 |
237 | The initKeyboardEvent method is deprecated.
238 |
239 |
240 |
241 |
DOMString typeArg
242 |
243 | Refer to the {{Event/initEvent()}} method for a description of this parameter.
244 |
245 |
246 |
boolean bubblesArg
247 |
248 | Refer to the {{Event/initEvent()}} method for a description of this parameter.
249 |
250 |
251 |
boolean cancelableArg
252 |
253 | Refer to the {{Event/initEvent()}} method for a description of this parameter.
254 |
255 |
256 |
Window? viewArg
257 |
258 | Specifies {{UIEvent/view}}. This value MAY be null.
259 |
260 |
261 |
DOMString keyArg
262 |
263 | Specifies {{KeyboardEvent/key}}.
264 |
265 |
266 |
unsigned long locationArg
267 |
268 | Specifies {{KeyboardEvent/location}}.
269 |
270 |
271 |
boolean ctrlKey
272 |
273 | Specifies whether the Control key modifier is active.
274 |
275 |
276 |
boolean altKey
277 |
278 | Specifies whether the Alt key modifier is active.
279 |
280 |
281 |
boolean shiftKey
282 |
283 | Specifies whether the Shift key modifier is active.
284 |
285 |
286 |
boolean metaKey
287 |
288 | Specifies whether the Meta key modifier is active.
289 |
290 |
291 |
292 |
293 |
294 |
Initializers for interface CompositionEvent
295 |
296 |
297 | The argument list to this legacy CompositionEvent initializer does not
298 | include the detailArg (present in other initializers) and
299 | adds the locale argument; it is
300 | necessary to preserve this inconsistency for compatibility with existing
301 | implementations.
302 |
318 | Initializes attributes of a CompositionEvent
319 | object. This method has the same behavior as
320 | UIEvent.initUIEvent(). The value of {{UIEvent/detail}}
321 | remains undefined.
322 |
323 |
324 | The initCompositionEvent method is deprecated.
325 |
326 |
327 |
328 |
DOMString typeArg
329 |
330 | Refer to the {{Event/initEvent()}} method for a description of this parameter.
331 |
332 |
333 |
boolean bubblesArg
334 |
335 | Refer to the {{Event/initEvent()}} method for a description of this parameter.
336 |
337 |
338 |
boolean cancelableArg
339 |
340 | Refer to the {{Event/initEvent()}} method for a description of this parameter.
341 |
342 |
343 |
Window? viewArg
344 |
345 | Specifies {{UIEvent/view}}. This value MAY be null.
346 |
20 | A collection of tools for viewing and testing various UI Events.
21 |
22 |
23 |
24 | To report a bug or a submit feature request for any of these tools,
25 | file an issue on Github.
26 |
27 |
28 |
Event Viewers
29 |
30 |
31 | Key Event Viewer
32 | View KeyboardEvents on a <input type="text"> element.
33 | Select which events and attributes to show and control event propagation.
34 | keydown, keypress, keyup, textinput, beforeinput, input, compositionstart, compositionupdate, compositionend
35 |
59 | These manual tests show a keyboard and require that you manually press the indicated
60 | keys. The key and code attributes of the KeyboardEvent will
61 | be checked against the known correct result for the layout.
62 |
63 |
64 |
65 | Note: Before running these tests, you must manually set your keyboard layout to match
66 | the layout being tested.
67 |