|
|
|
|
|
|
|
The DOM Level 2 Event Model is designed with two main goals. The first goal is the design of a generic event system which allows registration of event handlers, describes event flow through a tree structure, and provides basic contextual information for each event. Additionally, the specification will attempt to provide standard sets of events for user interface control and document mutation notifications, including defined contextual information for each of these event sets.
The second goal of the event model is to provide a common subset of the current event systems used within Microsoft Internet Explorer 4.0 and Netscape Navigator 4.0. This is intended to foster interoperability of existing scripts and content. It is not expected that this goal will be met with full backwards compatibility. However, the specification attempts to achieve this when possible.
The following constitutes the list of requirements for the DOM Level 2 Event Model.
Requirements of event flow:
Node.Requirements of event listener registration:
Requirements of contextual event information:
Requirements of event types:
Event flow is the process through which the an event originates from the DOM implementation
and is passed into the Document Object Model. The methods of event capture and event
bubbling, along with various event listener registration techniques, allow the event
to then be handled in a number of ways. It can be handled locally at the target
Node level or centrally from a Node higher in the document tree.
Each event has a Node toward which the event is directed by the DOM implementation. This
Node is the event target. When the event reaches the target, any event
listeners registered on the Node are triggered. Although all EventListeners
on the Node are guaranteed to receive the event, no specification is made as to the order
in which they will receive the event with regards to the other EventListeners on the
Node. If neither event
capture or event bubbling are in use for that particular event,
the event flow process will complete after all listeners have been triggered. If event capture
or event bubbling is in use, the event flow will be modified as described in the sections below.
Event capture is the process by which an ancestor of the event's target can register to intercept events of a given type before they are received by the event's target. Capture operates from the top of the tree downward, making it the symmetrical opposite of bubbling which is described below.
An EventListener being registered on an EventTarget
may choose to have that EventListener capture events by
specifying the useCapture parameter of the addEventListener
method to be true. Thereafter, when an event of the given type is
dispatched toward a descendant of the capturing object, the event
will trigger any capturing event listeners of the appropriate type
which exist in the direct line between the top of the document and the
event's target. This downward propagation continues until either no additional
capturing EventListeners are found or the event's target is
reached.
If the capturing EventListener wishes to prevent further
processing of the event it may call the preventCapture method of
the Event interface. This will prevent further dispatch of the event to additional
EventTargets lower in the tree structure, although additional EventListeners registered at
the same hierarchy level will still receive the event. Only one EventListeners
is required to call preventCapture to stop the propagation of the event
If no additional capturers exist and preventCapture has not been called,
the event triggers the appropriate EventListeners on the target
itself.
Although event capture is similar to the delegation based event
model, it is different in two important respects. First, event capture
only allows interception of events which are targeted at descendants
of the capturing Node. It does not allow interception of events
targeted to the capturer's ancestors, its siblings, or its
sibling's descendants. Secondly, event capture is not specified for
a single Node, it is specified for a specific type of event.
Once specified, event capture intercepts all events
of the specified type targeted toward any of the capturer's descendants.
Events which are designated as bubbling will initially proceed with the
same event flow as non-bubbling events. The event is dispatched to its target
Node and any event listeners found there are triggered. Bubbling
events will then trigger any additional event listeners found by following the
Node's parent chain upward, checking for any event listeners
registered on each successive Node. This upward propagation will continue
up to and including the Document.
Any event handler may choose to prevent continuation of the bubbling process
by calling the preventBubble method of the Event interface. If
any EventListener calls this method, all additional EventListeners
on the current EventTarget will be triggered but bubbling
will cease at that level. Only one call to preventBubble is required to
prevent further bubbling.
Some events are specified as cancellable. For these events, the
DOM implementation generally has a default action associated with the
event. Before processing these events, the implementation must check for
event listeners registered to receive the event and dispatch the event to
those listeners. These listeners then have the option of cancelling the
implementation's default action or allowing the default action to proceed.
Cancellation is accomplished by calling the Event's
preventDefault method. If one or more EventListeners call
preventDefault during any phase of event flow the default action will
be cancelled.
The EventTarget interface is implemented by all Nodes in
an implementation which supports the DOM Event Model. The interface allows event listeners
to be registered on the node.
interface EventTarget {
void addEventListener(in DOMString type,
in EventListener listener,
in boolean useCapture);
void removeEventListener(in DOMString type,
in EventListener listener,
in boolean useCapture);
};
addEventListenertype |
The event type for which the user is registering | |
listener |
The | |
useCapture |
If true, |
removeEventListenerEventListener is removed from an EventTarget while it is
processing an event, it will complete its current actions but will not be triggered
again during any later stages of event flow.
type |
Specifies the event type of the | |
listener |
The | |
useCapture |
Specifies whether the |
The EventListener interface is the primary method for handling events.
Users implement the EventListener interface and register their listener
on a EventTarget using the AddEventListener method. The
users should also remove their EventListener from its
EventTarget after they have completed using the listener.
interface EventListener {
void handleEvent(in Event event);
};
handleEvent
EventListener interface was registered.
event |
The |
In HTML 4.0, event listeners were specified as properties of an element. As such,
registration of a second event listener of the same type would replace the
first listener. The DOM Event Model allows registration of multiple event listeners on
a single Node. To achieve this, event listeners are no longer stored as property
values.
In order to achieve compatibility with HTML 4.0, implementors may view the setting of
properties which represent event handlers as the creation and registration of an
EventListener on the Node. The value of useCapture
defaults to false. This EventListener behaves in
the same manner as any other EventListenerss which may be registered on the
EventTarget. If the property representing the event listener is changed, this may be
viewed as the removal of the previously registered EventListener and the
registration of a new one. No technique is provided to allow HTML 4.0 event listeners
access to the context information defined for each event.
The specification currently defines listeners as generic listeners which can be registered for multiple types of events. This solution avails itself readily to extending or creating new events. However, registering the same object for multiple events requires the user to differentiate between the events inside the event listener. The current string based event typing system could make this very inefficient. The DOM Working Group is exploring alternatives to the string based event typing to resolve this issue.
A full solution has not yet been added to meet the suggestion that all listeners
be notified of the final resolution of an event. It is possible that use of both pre- and
post-processed types of events will achieve this goal but it is not yet clear if this solution
will be sufficient.
The Event interface is used to provide contextual information about an event
to the handler processing the event. An object which implements the Event interface
is generally passed as the first parameter to an event handler. More specific
context information is passed to event handlers by deriving additional interfaces from
Event which contain information directly relating to the type of event
they accompany. These derived interfaces are also implemented by the object passed to the
event listener.
interface Event {
// PhaseType
const unsigned short BUBBLING_PHASE = 1;
const unsigned short CAPTURING_PHASE = 2;
const unsigned short AT_TARGET = 3;
attribute DOMString type;
attribute Node target;
attribute Node currentNode;
attribute unsigned short eventPhase;
void preventBubble();
void preventCapture();
void preventDefault();
};
An integer indicating which phase of event flow is being processed.
| BUBBLING_PHASE |
The current event phase is the bubbling phase. |
| CAPTURING_PHASE |
The current event phase is the capturing phase. |
| AT_TARGET |
The event is currently being evaluated at the target node. |
typetype property represents the event name as a string property.
targettarget property indicates the Node to which the event
was originally dispatched.
currentNodecurrentNode property indicates to which Node the event
is currently being dispatched. This is particularly useful during capturing and bubbling.
eventPhaseeventPhase property indicates which phase of event flow is currently
being evaluated.
preventBubblepreventBubble method is used to end the bubbling phase of
event flow. If this method is called by any EventListeners registered
on the same EventTarget during bubbling, the bubbling phase will cease at that
level and the event will not be propagated upward within the tree.
preventCapturepreventCapture method is used to end the capturing phase of
event flow. If this method is called by any EventListeners registered
on the same EventTarget during capturing, the capturing phase will cease at that
level and the event will not be propagated any further down.
preventDefaultpreventCapture method is used
to signify that the event is to be cancelled. If, during any stage of event flow,
the preventDefault method is called the event is cancelled.
Any default action associated with the event will not occur. Calling this method
for a non-cancellable event has no effect.
The UIEvent interface provides specific contextual
information associated with User Interface and Logical events.
interface UIEvent : Event {
const int CHAR_UNDEFINED = 1;
const int KEY_FIRST = 1;
const int KEY_LAST = 1;
const int VK_0 = 1;
const int VK_1 = 1;
const int VK_2 = 1;
const int VK_3 = 1;
const int VK_4 = 1;
const int VK_5 = 1;
const int VK_6 = 1;
const int VK_7 = 1;
const int VK_8 = 1;
const int VK_9 = 1;
const int VK_A = 1;
const int VK_ACCEPT = 1;
const int VK_ADD = 1;
const int VK_AGAIN = 1;
const int VK_ALL_CANDIDATES = 1;
const int VK_ALPHANUMERIC = 1;
const int VK_ALT = 1;
const int VK_ALT_GRAPH = 1;
const int VK_AMPERSAND = 1;
const int VK_ASTERISK = 1;
const int VK_AT = 1;
const int VK_B = 1;
const int VK_BACK_QUOTE = 1;
const int VK_BACK_SLASH = 1;
const int VK_BACK_SPACE = 1;
const int VK_BRACELEFT = 1;
const int VK_BRACERIGHT = 1;
const int VK_C = 1;
const int VK_CANCEL = 1;
const int VK_CAPS_LOCK = 1;
const int VK_CIRCUMFLEX = 1;
const int VK_CLEAR = 1;
const int VK_CLOSE_BRACKET = 1;
const int VK_CODE_INPUT = 1;
const int VK_COLON = 1;
const int VK_COMMA = 1;
const int VK_COMPOSE = 1;
const int VK_CONTROL = 1;
const int VK_CONVERT = 1;
const int VK_COPY = 1;
const int VK_CUT = 1;
const int VK_D = 1;
const int VK_DEAD_ABOVEDOT = 1;
const int VK_DEAD_ABOVERING = 1;
const int VK_DEAD_ACUTE = 1;
const int VK_DEAD_BREVE = 1;
const int VK_DEAD_CARON = 1;
const int VK_DEAD_CEDILLA = 1;
const int VK_DEAD_CIRCUMFLEX = 1;
const int VK_DEAD_DIAERESIS = 1;
const int VK_DEAD_DOUBLEACUTE = 1;
const int VK_DEAD_GRAVE = 1;
const int VK_DEAD_IOTA = 1;
const int VK_DEAD_MACRON = 1;
const int VK_DEAD_OGONEK = 1;
const int VK_DEAD_SEMIVOICED_SOUND = 1;
const int VK_DEAD_TILDE = 1;
const int VK_DEAD_VOICED_SOUND = 1;
const int VK_DECIMAL = 1;
const int VK_DELETE = 1;
const int VK_DIVIDE = 1;
const int VK_DOLLAR = 1;
const int VK_DOWN = 1;
const int VK_E = 1;
const int VK_END = 1;
const int VK_ENTER = 1;
const int VK_EQUALS = 1;
const int VK_ESCAPE = 1;
const int VK_EURO_SIGN = 1;
const int VK_EXCLAMATION_MARK = 1;
const int VK_F = 1;
const int VK_F1 = 1;
const int VK_F10 = 1;
const int VK_F11 = 1;
const int VK_F12 = 1;
const int VK_F13 = 1;
const int VK_F14 = 1;
const int VK_F15 = 1;
const int VK_F16 = 1;
const int VK_F17 = 1;
const int VK_F18 = 1;
const int VK_F19 = 1;
const int VK_F2 = 1;
const int VK_F20 = 1;
const int VK_F21 = 1;
const int VK_F22 = 1;
const int VK_F23 = 1;
const int VK_F24 = 1;
const int VK_F3 = 1;
const int VK_F4 = 1;
const int VK_F5 = 1;
const int VK_F6 = 1;
const int VK_F7 = 1;
const int VK_F8 = 1;
const int VK_F9 = 1;
const int VK_FINAL = 1;
const int VK_FIND = 1;
const int VK_FULL_WIDTH = 1;
const int VK_G = 1;
const int VK_GREATER = 1;
const int VK_H = 1;
const int VK_HALF_WIDTH = 1;
const int VK_HELP = 1;
const int VK_HIRAGANA = 1;
const int VK_HOME = 1;
const int VK_I = 1;
const int VK_INSERT = 1;
const int VK_INVERTED_EXCLAMATION_MARK = 1;
const int VK_J = 1;
const int VK_JAPANESE_HIRAGANA = 1;
const int VK_JAPANESE_KATAKANA = 1;
const int VK_JAPANESE_ROMAN = 1;
const int VK_K = 1;
const int VK_KANA = 1;
const int VK_KANJI = 1;
const int VK_KATAKANA = 1;
const int VK_KP_DOWN = 1;
const int VK_KP_LEFT = 1;
const int VK_KP_RIGHT = 1;
const int VK_KP_UP = 1;
const int VK_L = 1;
const int VK_LEFT = 1;
const int VK_LEFT_PARENTHESIS = 1;
const int VK_LESS = 1;
const int VK_M = 1;
const int VK_META = 1;
const int VK_MINUS = 1;
const int VK_MODECHANGE = 1;
const int VK_MULTIPLY = 1;
const int VK_N = 1;
const int VK_NONCONVERT = 1;
const int VK_NUM_LOCK = 1;
const int VK_NUMBER_SIGN = 1;
const int VK_NUMPAD0 = 1;
const int VK_NUMPAD1 = 1;
const int VK_NUMPAD2 = 1;
const int VK_NUMPAD3 = 1;
const int VK_NUMPAD4 = 1;
const int VK_NUMPAD5 = 1;
const int VK_NUMPAD6 = 1;
const int VK_NUMPAD7 = 1;
const int VK_NUMPAD8 = 1;
const int VK_NUMPAD9 = 1;
const int VK_O = 1;
const int VK_OPEN_BRACKET = 1;
const int VK_P = 1;
const int VK_PAGE_DOWN = 1;
const int VK_PAGE_UP = 1;
const int VK_PASTE = 1;
const int VK_PAUSE = 1;
const int VK_PERIOD = 1;
const int VK_PLUS = 1;
const int VK_PREVIOUS_CANDIDATE = 1;
const int VK_PRINTSCREEN = 1;
const int VK_PROPS = 1;
const int VK_Q = 1;
const int VK_QUOTE = 1;
const int VK_QUOTEDBL = 1;
const int VK_R = 1;
const int VK_RIGHT = 1;
const int VK_RIGHT_PARENTHESIS = 1;
const int VK_ROMAN_CHARACTERS = 1;
const int VK_S = 1;
const int VK_SCROLL_LOCK = 1;
const int VK_SEMICOLON = 1;
const int VK_SEPARATER = 1;
const int VK_SHIFT = 1;
const int VK_SLASH = 1;
const int VK_SPACE = 1;
const int VK_STOP = 1;
const int VK_SUBTRACT = 1;
const int VK_T = 1;
const int VK_TAB = 1;
const int VK_U = 1;
const int VK_UNDEFINED = 1;
const int VK_UNDERSCORE = 1;
const int VK_UNDO = 1;
const int VK_UP = 1;
const int VK_V = 1;
const int VK_W = 1;
const int VK_X = 1;
const int VK_Y = 1;
const int VK_Z = 1;
attribute long screenX;
attribute long screenY;
attribute long clientX;
attribute long clientY;
attribute boolean ctrlKey;
attribute boolean shiftKey;
attribute boolean altKey;
attribute boolean metaKey;
attribute unsigned long keyCode;
attribute unsigned long charCode;
attribute unsigned short button;
attribute unsigned short clickCount;
};
KEY_PRESSED and KEY_RELEASED events which do not map to a valid Unicode character use this for the keyChar value.
The first number in the range of ids used for key events.
The last number in the range of ids used for key events.
VK_0 thru VK_9 are the same as ASCII '0' thru '9' (0x30 - 0x39)
VK_A thru VK_Z are the same as ASCII 'A' thru 'Z' (0x41 - 0x5A)
Constant for the All Candidates function key.
Constant for the Alphanumeric function key.
Constant for the AltGraph modifier key.
Constant for the "@" key.
Constant for the "^" key.
Constant for the Code Input function key.
Constant for the ":" key.
Constant for the Compose function key.
Constant for the "$" key.
Constant for the Euro currency sign key.
Constant for the "!" key.
Constant for the F1 function key.
Constant for the F10 function key.
Constant for the F11 function key.
Constant for the F12 function key.
Constant for the F13 function key.
Constant for the F14 function key.
Constant for the F15 function key.
Constant for the F16 function key.
Constant for the F17 function key.
Constant for the F18 function key.
Constant for the F19 function key.
Constant for the F2 function key.
Constant for the F20 function key.
Constant for the F21 function key.
Constant for the F22 function key.
Constant for the F23 function key.
Constant for the F24 function key.
Constant for the F3 function key.
Constant for the F4 function key.
Constant for the F5 function key.
Constant for the F6 function key.
Constant for the F7 function key.
Constant for the F8 function key.
Constant for the F9 function key.
Constant for the Full-Width Characters function key.
Constant for the Half-Width Characters function key.
Constant for the Hiragana function key.
Constant for the inverted exclamation mark key.
Constant for the Japanese-Hiragana function key.
Constant for the Japanese-Katakana function key.
Constant for the Japanese-Roman function key.
Constant for the Katakana function key.
for KeyPad cursor arrow keys
for KeyPad cursor arrow keys
for KeyPad cursor arrow keys
for KeyPad cursor arrow keys
Constant for the "(" key.
Constant for the "#" key.
Constant for the "+" key.
Constant for the Previous Candidate function key.
Constant for the ")" key.
Constant for the Roman Characters function key.
KEY_TYPED events do not have a keyCode value.
Constant for the "_" key.
screenXscreenX indicates the horizontal coordinate at which the event occurred in
relative to the origin of the screen coordinate system.
screenYscreenY indicates the vertical coordinate at which the event occurred
relative to the origin of the screen coordinate system.
clientXclientX indicates the horizontal coordinate at which the event occurred
relative to the DOM implementation's client area.
clientYclientY indicates the vertical coordinate at which the event occurred
relative to the DOM implementation's client area.
ctrlKeyctrlKey indicates whether the 'ctrl' key was depressed during the firing
of the event.
shiftKeyshiftKey indicates whether the 'shift' key was depressed during the firing
of the event.
altKeyaltKey indicates whether the 'alt' key was depressed during the firing
of the event. On some platforms this key may map to an alternative key name.
metaKeymetaKey indicates whether the 'meta' key was depressed during the firing
of the event. On some platforms this key may map to an alternative key name.
keyCodekeyCode holds the virtual key code value of the key which was
depressed if the event is a key event. Otherwise, the value is zero.
charCodecharCode holds the value of the Unicode character associated with the depressed
key if the event is a key event. Otherwise, the value is zero.
buttonbutton
is used to indicate which mouse button changed state.
clickCountclickCount property indicates the number of times a mouse button has been pressed
and released over the same screen location during a user action. The property value is 1 when
the user begins this action and increments by 1 for each full sequence of pressing and releasing.
If the user moves the mouse between the mousedown and mouseup the value will be set to 0,
indicating that no click is occurring.
The MutationEvent interface provides specific contextual
information associated with Mutation events.
interface MutationEvent : Event {
attribute Node relatedNode;
attribute DOMString prevValue;
attribute DOMString newValue;
attribute DOMString attrName;
};
relatedNoderelatedNode is used to identify a secondary node related to a mutation event.
For example, if a mutation event is dispatched to a node indicating that its parent
has changed, the relatedNode is the changed parent. If an event is instead
dispatch to a subtree indicating a node was changed within it, the relatedNode
is the changed node.
prevValueprevValue indicates the previous value of text nodes and attributes in
attrModified and charDataModified events.
newValuenewValue indicates the new value of text nodes and attributes in
attrModified and charDataModified events.
attrNameattrName indicates the changed attr in the attrModified event.
The DOM Level 2 Event Model allows a DOM implementation to support multiple sets of events. The model has been designed to allow addition of new event sets as is required. The DOM will not attempt to define all possible events. For purposes of interoperability, the DOM will define a set of user interface events, a set of UI logical events, and a set of document mutation events.
The User Interface event set is composed of events listed in HTML 4.0 and additional events which are supported in both Netscape Navigator 4.0 and Microsoft Internet Explorer 4.0.
mousedown
mouseup
click
clickCount property incrementing with each repetition.
This event is valid for most elements.The mutation event set is designed to allow notification of any changes to the structure of a document, including attr and text modifications. It may be noted that none of the mutation events listed are designated as cancellable. The reasoning for this stems from the fact that it would be very difficult to make use of existing DOM interfaces which cause document modifications if any change to the document might or might not take place due to cancellation of the related event. Although this is still a desired capability, it was decided that it would be better left until the addition of transactions into the DOM.
Attr has been modified on a node. The target of this
event is the node whose Attr changed.The HTML event set is composed of events listed in HTML 4.0 and additional events which are supported in both Netscape Navigator 4.0 and Microsoft Internet Explorer 4.0.
|
|
|
|