Status of this document

This section describes the status of this document at the
time of its publication. Other documents may supersede this
document. The latest status of this document series is maintained
at the W3C.

This is a W3C Working Draft for review by W3C members and other
interested parties.

It is a draft document and may be updated, replaced or obsoleted
by other documents at any time. It is inappropriate to use W3C
Working Drafts as reference material or to cite them as other than
"work in progress". This is work in progress and does not imply
endorsement by, or the consensus of, either W3C or members of the
DOM working group.

Copyright Notice

This document is published under the W3C Document
Copyright Notice and License. The bindings within this document
are published under the W3C Software
Copyright Notice and License. The software license requires
"Notice of any changes or modifications to the W3C files, including
the date changes were made." Consequently, modified versions of the
DOM bindings must document that they do not conform to the W3C
standard; in the case of the IDL definitions, the pragma prefix can
no longer be 'w3c.org'; in the case of the Java language binding,
the package names can no longer be in the 'org.w3c' package.

Public documents on the W3C site are provided by the copyright
holders under the following license. The software or Document Type
Definitions (DTDs) associated with W3C specifications are governed
by the Software
Notice. By using and/or copying this document, or the W3C
document from which this statement is linked, you (the licensee)
agree that you have read, understood, and will comply with the
following terms and conditions:

Permission to use, copy, and distribute the contents of this
document, or the W3C document from which this statement is linked,
in any medium for any purpose and without fee or royalty is hereby
granted, provided that you include the following on ALL
copies of the document, or portions thereof, that you use:

When space permits, inclusion of the full text of this
NOTICE should be provided. We request that authorship
attribution be provided in any software, documents, or other items
or products that you create pursuant to the implementation of the
contents of this document, or any portion thereof.

No right to create modifications or derivatives of W3C documents
is granted pursuant to this license. However, if additional
requirements (documented in the Copyright
FAQ) are satisfied, the right to create modifications or
derivatives is sometimes granted by the W3C to individuals
complying with those requirements.

THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO
REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT
NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS
OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE
IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY
PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT,
SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE
DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS
THEREOF.

The name and trademarks of copyright holders may NOT be used in
advertising or publicity pertaining to this document or its
contents without specific, written prior permission. Title to
copyright in this document will at all times remain with copyright
holders.

This W3C work (including software, documents, or other related
items) is being provided by the copyright holders under the
following license. By obtaining, using and/or copying this work,
you (the licensee) agree that you have read, understood, and will
comply with the following terms and conditions:

Permission to use, copy, and modify this software and its
documentation, with or without modification, for any purpose and
without fee or royalty is hereby granted, provided that you include
the following on ALL copies of the software and documentation or
portions thereof, including modifications, that you make:

The full text of this NOTICE in a location viewable to users of
the redistributed or derivative work.

Notice of any changes or modifications to the W3C files,
including the date changes were made. (We recommend you provide
URIs to the location from which the code is derived.)

THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND
COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE
USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD
PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT,
SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE
SOFTWARE OR DOCUMENTATION.

The name and trademarks of copyright holders may NOT be used in
advertising or publicity pertaining to the software without
specific, written prior permission. Title to copyright in this
software and any associated documentation will at all times remain
with copyright holders.

10 April 2001

1. Document Object Model
Events

Editors

Tom Pixley, Netscape Communications Corporation

Table of contents

1.1. Level 3
Events Overview

The goal of the DOM Level 3 Events specification is to expand
upon the functionality specified in the DOM Level 2 Event
Specification. The specification does this by adding new interfaces
which are complimentary to the interfaces defined in the DOM Level
2 Event Specification as well as adding new event modules to those
already defined.

This specification requires the previously designed interfaces
in order to be functional. It is not designed to be standalone.
These interfaces are not designed to supercede the interfaces
already provided but instead to add to the functionality contained
within them.

1.2. Level 3
Events Interfaces

1.2.1.
Key events

A DOM application may use the hasFeature(feature,
version) method of the DOMImplementation
interface with parameter values "KeyEvents" and "3.0"
(respectively) to determine whether or not the Mouse event module
is supported by the implementation. In order to fully support this
module, an implementation must also support the "UIEvents" feature
defined in this specification. Please, refer to additional
information about conformance in the DOM Level 3 Core specification
.

Note: To create an instance of the KeyEvent
interface, use the feature string "KeyEvents" as the value of the
input parameter used with the createEvent method of
the DocumentEvent interface.

The inputGenerated attribute indicates whether the
key event will normally cause visible output. If the key event does
not generate any visible output, such as the use of a function key
or the combination of certain modifier keys used in conjunction
with another key, then the value will be false. If visible output
is normally generated by the key event then the value will be
true.
The value of inputGenerated does not guarantee the
creation of a character. If a key event causing visible output is
cancelable it may be prevented from causing output. This attribute
is intended primarily to differentiate between keys events which
may or may not produce visible output depending on the system
state.

The numPad attribute indicates whether or not the
key event was generated on the number pad section of the keyboard.
If the number pad was used to generate the key event the value is
true, otherwise the value is false.

outputString holds the value of the output
generated by the key event. This may be a single Unicode character
or it may be a string. It may also be null in the case where no
output was generated by the key event.

When the key associated with a key event is not representable
via a Unicode character virtKeyVale holds the virtual
key code associated with the depressed key. If the key has a
Unicode representation or no virtual code is available the value is
DOM_VK_UNDEFINED.

The CheckModifier method is used
to check the status of a single modifier key associated with a
KeyEvent. The identifier of the modifier in question
is passed into the CheckModifier function. If the
modifier is triggered it will return true. If not, it will return
false.
The list of keys below represents the allowable modifier paramaters
for this method.

The initKeyEvent method is used to
initialize the value of a MouseEvent created through
the DocumentEvent interface. This method may only be
called before the KeyEvent has been dispatched via the
dispatchEvent method, though it may be called multiple times during
that phase if necessary. If called multiple times, the final
invocation takes precedence. This method has no effect if called
after the event has been dispatched.

The initModifier method is used to
initialize the values of any modifiers associated with a
KeyEvent created through the
DocumentEvent interface. This method may only be
called before the KeyEvent has been dispatched via the
dispatchEvent method, though it may be called multiple times during
that phase if necessary. If called multiple times with the same
modifier property the final invocation takes
precedence. Unless explicitly give a value of true, all modifiers
have a value of false. This method has no effect if called after
the event has been dispatched.
The list of keys below represents the allowable modifier paramaters
for this method.

DOM_VK_LEFT_ALT

DOM_VK_RIGHT_ALT

DOM_VK_LEFT_CONTROL

DOM_VK_RIGHT_CONTROL

DOM_VK_LEFT_SHIFT

DOM_VK_RIGHT_SHIFT

DOM_VK_META

Parameters

modifier of type
unsigned long

The modifier which the user wishes to initialize

value of type
boolean

The new value of the modifier.

No Return Value

No Exceptions

There are two major groups of key events. The first contains the
textEvent event. The textEvent event
indicates that text information has been entered, either in the
form of printable characters or non-printable text information such
as modifier keys. textEvent events are not necessarily
accompanied by the events of the second major groups of key events,
keydown and keyup.

textEvent

The textEvent event indicates that text information has been
entered. The text information entered can originate from a variety
of sources. It could, for example, be a character resulting from a
keypress. It could also be a string resulting from an input method.

Bubbles: Yes

Cancelable: Yes

The keydown and keyup events comprise
the second group of key events. These events are fired to indicate
the physical motion of the keys on the character generation device.
Depending on the input system being used, textEvent
events may or may not be generated for each pair of
keydown and keyup events.

keydown

The keydown event occurs when a key is pressed down.

Bubbles: Yes

Cancelable: Yes

keyup

The keyup event occurs when a key is released.

Bubbles: Yes

Cancelable: Yes

1.2.2.
EventListener Grouping

EventListener grouping is intended to allow groups of
EventListeners to be registered which will each have
independent event flow within them which is not affected by changes
to event flow in any other group. This may be used to control
events separately in multiple views on a document. It may also be
used to develop an application which uses events without the
problem of possible interference by other applications running
within the same document.

The new interfaces added for EventListener grouping should not
interfere with the interfaces established in the Level 2 DOM. For
purposes of interoperability between the Level 2 DOM Event Model
and the new interfaces added in Level 3 the implementation can be
assumed to define a default EventGroup.
This EventGroup is
implicitly used in the registration of all
EventListeners registered via the Level 2 DOM Event
Model methods which do not specify an EventGroup.

The EventGroup interface functions primarily as a placeholder
for separating the event flows when there are multiple groups of
listeners for a DOM tree.

EventListeners can be registered without an
EventGroup using the existing EventTarget
interface, or with an associated EventGroup using the
new EventTargetGroup
interface. When an event is dispatched, it is dispatched
independently to each EventGroup. In particular, the
stopPropagation method of the Event
interface only stops propagation within an
EventListener's associated
EventGroup.

The EventTargetGroup interface is implemented by the same set of
objects that implement the EventTarget interface,
namely all EventTargets in in implementation which
supports the Event model and the EventGroup extension.

This method is equivalent to the
removeEventListener method of the
EventTarget interface, with the exception of the added
eventGroup parameter. The listener registered with
this EventGroup
associated is removed.

The DocumentEventGroup interface provides a
mechanism by which the user can create an EventGroup of
a type supported by the implementation. It is expected that the
DocumentEvent interface will be implemented on the
same object which implements the Documentinterface in
an implementation which supports the EventGroupextension.

1.3. Issues

Issue getModifier:

Why is modifier state exposed through a method rather than an
attribute?Resolution: The modifier keys are not currently
representable as bit flags. Setting them individually would
therefore require an attribute for each. Rather than bloat the api,
especially given the addition of left and right modifier keys, the
modifiers are exposed via a single method.

Issue ISO-IEC-9995:

Have you coordinated this set with that defined by ISO/IEC 9995
which addresses various Keyboard symbol issues.Resolution: Upon examination of the ISO spec we found it to
be insufficient to our needs. It does not represent the left/right
differentiation between some keys. It also lacks function
keys.

Issue ISO-IEC-14755:

Review ISO/IEC 14755 "Input methods to enter characters from
the repertoire of ISO/IEC 10646 with a keyboard or other input
device" to insure that the treatment of input state is consistent
with that expected by current practice when it comes to platforms
which support input methods.

Issue offsets:

(This issue is related with mouse events and Views?)
it would be useful if MouseEvent class had a property that would
enable listners to learn about coordinates of the event within the
element's own coordinate system.

Issue unicodeidents:

Some of the unicode chars are pretty esoteric (i.e. home, end,
scroll lock). Do we want to adopt these or will this be harder on
users than defining them in the DOM Event Spec. About a dozen keys
fit this pattern.

Issue texteventwithoutchargeneration:

The results of the discussions on switching the keypress event
out for the textEvent were inconclusive on the question of whether
to fire textEvents for non character generating keys input. This
includes modifier keys, function keys, etc.

This method has no return value.
The typeArg parameter is of type String.
The canBubbleArg parameter is of type Boolean.
The cancelableArg parameter is of type Boolean.
The viewArg parameter is a AbstractView object.
The detailArg parameter is of type Number.
The outputStringArg parameter is of type
String.
The keyValArg parameter is of type Number.
The virtKeyValArg parameter is of type Number.
The inputGeneratedArg parameter is of type
Boolean.
The numPadArg parameter is of type Boolean.

initModifier(modifier, value)

This method has no return value.
The modifier parameter is of type Number.
The value parameter is of type Boolean.

Object EventGroup

The EventGroup object has the following methods:

isSameEventGroup(eventGroup)

This method returns a Boolean.
The eventGroup parameter is a EventGroup object.

Object EventTargetGroup

The EventTargetGroup object has the following
methods:

addEventListener(type, listener, useCapture,
eventGroup)

This method has no return value.
The type parameter is of type String.
The listener parameter is a EventListener
object.
The useCapture parameter is of type Boolean.
The eventGroup parameter is a EventGroup object.

removeEventListener(type, listener, useCapture,
eventGroup)

This method has no return value.
The type parameter is of type String.
The listener parameter is a EventListener
object.
The useCapture parameter is of type Boolean.
The eventGroup parameter is a EventGroup object.

Object DocumentEventGroup

The DocumentEventGroup object has the following
methods:

createEventGroup()

This method returns a EventGroup object.

10 April 2001

References

For the latest version of any W3C specification please consult
the list of W3C Technical
Reports available at http://www.w3.org/TR.

OMG (Object Management Group)
IDL (Interface Definition Language) defined in The Common Object
Request Broker: Architecture and Specification, version 2.3.1,
October 1999. Available from http://www.omg.org