Le modèle d'événement DOM niveau 2 est construit selon deux buts principaux. Le premier but est la conception d'un système d'événements génériques qui permet d'enregistrer des gestionnaires d'événement, de décrire le flux d'événement à travers une structure d'arbre et de fournir des données de contexte de base pour chaque événement. En outre, la spécification fournira des modules d'événements standards pour le contrôle de l'interface utilisateur et les notifications de mutation de document, y compris les données de contexte définies pour chacun de ces modules d'événements.
Le second but du modèle d'événements est de fournir un sous-ensemble commun aux systèmes d'événements actuels employés dans les navigateurs DOM niveau 0. L'intention est d'assurer l'interopérabilité des scripts et contenus existants. Cet objectif ne prévoit pas une rétrocompatibilité complète. Cette spécification essaye toutefois d'y parvenir quand c'est possible.
Les sections suivantes de la spécification du modèle d'événement définissent à la fois le modèle d'événement DOM
et un certain nombre de modules d'événements conformes prévus pour ce modèle. Le modèle d'événement est constitué par les deux sections
traitant de la propagation des événements et de l'enregistrement des guetteurs d'événement et par la section décrivant l'interface Event
.
Une application DOM peut utiliser la méthode hasFeature(feature, version)
de l'interface DOMImplementation
, respectivement avec les valeurs de paramètre "Events" et "2.0", pour déterminer
si le module d'événement est reconnu par la mise en œuvre ou non. Pour une gestion complète de ce module,
une mise en œuvre DOM doit également gérer la fonctionnalité "Core", définie par la
spécification du DOM niveau 2 Core [DOM niveau 2 Core].
Pour d'autres renseignements, consulter la section sur la
conformité →vf
dans la spécification du DOM niveau 2 Core [DOM niveau 2 Core].
Chaque module d'événement décrit sa propre chaîne caractéristique dans la liste des modules d'événements.
Le flux d'événement est le processus selon lequel un événement naît dans
la mise en œuvre DOM puis se transmet dans le modèle objet de document. Les méthodes de la capture et du bouillonnement
des événements, associées aux techniques d'enregistrement diverses des guetteurs d'événement, permettent de manipuler les événements
de plusieurs façons. L'événement peut être manipulé localement au niveau de l'objet EventTarget
ou à distance depuis
un objet EventTarget
central en amont dans l'arbre du document.
Chaque événement a un objet EventTarget
vers lequel
la mise en œuvre DOM dirige l'événement. Cet objet EventTarget
est défini dans l'attribut target
de l'objet Event
.
Lorsque l'événement atteint la cible, tous les guetteurs d'événement enregistrés sur cet objet
EventTarget
sont déclenchés. Bien que
tous les objets guetteurs d'événement EventListener
sur l'objet
EventTarget
soient assurés d'un déclenchement lorsque
la cible d'événement reçoit un événement, rien n'est défini en ce qui concerne l'ordre de distribution de l'événement
aux guetteurs EventListener
de cet objet
EventTarget
.
Si ni capture ni bouillonnement d'événement ne sont actifs pour cet événement particulier, alors le processus de flux d'événement
s'achèvera après que tous les guetteurs auront été déclenchés. Si la capture ou le bouillonnement d'événement sont actifs, alors
le flux d'événement sera modifié selon les descriptions des sections suivantes.
Aucune exception soulevée dans un objet EventListener
n'arrêtera
la propagation de l'événement. Son traitement se poursuivra auprès de tous les autres guetteurs
EventListener
de la façon décrite.
Il est prévu que les actions entreprises par un objet EventListener
puissent initier d'autres événements. Leur manipulation devrait être synchrone et
leur réintroduction dans le modèle d'événement est possible.
La capture d'événement est le processus selon lequel un objet EventListener
, enregistré sur un
ancêtre de la cible d'événement, peut intercepter
les événements d'un type donné avant qu'ils ne soient reçus par la cible d'événement.
La capture opère en aval depuis le sommet de l'arbre, qui est généralement le nœud Document
,
ce qui en fait l'opposé symétrique du bouillonnement décrit ensuite. La chaîne des
objets EventTarget
depuis le sommet de l'arbre vers la cible d'événement,
se détermine avant la distribution initiale de l'événement.
Si des modifications se produisent sur l'arbre pendant le traitement de l'événement, le flux d'événement se poursuivra
conformément à l'état initial de l'arbre.
Lors de son enregistrement sur un objet EventTarget
,
on peut paramétrer le guetteur EventListener
pour capturer les événements
en donnant la valeur true
au paramètre useCapture
de la méthode addEventListener
.
Donc, lorsqu'un événement de type donné est distribué à un descendant
de l'objet capturant, l'événement va déclencher tous les guetteurs d'événement capturants de ce type qui existent en ligne directe
entre le sommet du document et la cible d'événement. Cette propagation vers le bas se poursuit jusqu'à ce que
la cible d'événement soit atteinte. Un guetteur EventListener
capturant ne sera pas déclenché par un événement distribué directement à l'objet
EventTarget
sur lequel il est enregistré.
Si le guetteur EventListener
capturant souhaite empêcher la
poursuite du traitement de l'événement, il peut appeler la méthode stopProgagation
de
l'interface Event
. Cela empêchera la redistribution de l'événement,
quoique les autres guetteurs EventListener
enregistrés
au même niveau hiérarchique continueront de recevoir l'événement. Une fois la méthode stopPropagation
invoquée,
les autres appels de cette méthode n'auront aucun effet. S'il n'y a pas d'autre guetteur capturant et si la méthode stopPropagation
n'est pas invoquée, l'événement déclenche les guetteurs EventListener
appropriés sur la cible en question.
Bien que la capture d'événement ressemble à un modèle d'événement fondé sur la délégation, selon lequel toutes les parties intéressées
enregistrent leurs guetteurs directement sur la cible dont elles souhaitent recevoir des notifications, elle en diffère par
deux aspects importants. Premièrement, la capture d'événement permet seulement d'intercepter les événements adressés aux
descendants de l'objet
EventTarget
capturant. Elle ne permet pas d'intercepter les événements adressés
aux ancêtres de l'objet capturant, à ses frères
ou aux descendants de ces frères. Deuxièmement, la capture d'événement n'est pas définie
pour un seul objet EventTarget
mais pour un type particulier
d'événement. Une fois définie, la capture d'événement intercepte tous les événements du type indiqué adressés aux
descendants du capturant.
Les événements qualifiés de bouillonnants poursuivront selon un flux d'événement initial identique aux non bouillonnants.
L'événement est distribué vers sa cible EventTarget
et tous les
guetteurs d'événement qui s'y trouvent sont déclenchés. Les événements par bouillonnement déclencheront alors tous les autres
guetteurs d'événements trouvés en remontant la chaîne du parent de
l'objet EventTarget
, en sollicitant chaque guetteur d'événement
enregistré sur chaque objet EventTarget
successif.
Cette propagation en amont continuera jusqu'au nœud Document
inclus. Les guetteurs
EventListener
enregistrés comme capturants ne seront pas déclenchés
pendant cette phase. La chaîne des objets EventTarget
,
depuis la cible d'événement jusqu'au sommet de l'arbre, se détermine avant la distribution initiale de l'événement.
Si des modifications se produisent sur l'arbre pendant le traitement de l'événement, le flux d'événement se poursuivra
conformément à l'état initial de l'arbre.
Tout gestionnaire d'événement peut empêcher la propagation ultérieure de
l'événement en appelant la méthode stopPropagation
de l'interface Event
.
Si un guetteur EventListener
appelle cette méthode, tous les objets
EventListener
sur l'objet
EventTarget
courant seront déclenchés mais le
bouillonnement cessera à ce niveau. Un seul appel de la méthode stopPropagation
suffit pour empêcher
la poursuite du bouillonnement.
Certains événements sont définis comme étant annulables. Le cas échéant, la mise en œuvre DOM entreprend généralement l'action implicite associée à l'événement. Un exemple serait celui d'un hyperlien dans un navigateur Web. Quand l'utilisateur clique sur l'hyperlien, l'action implicite revient en général à activer cet hyperlien. Avant le traitement de tels événements, la mise en œuvre doit vérifier la présence de guetteurs d'événement enregistrés pour ce type d'événement afin de leur distribuer ces événements. Ces guetteurs sont alors face au choix d'annuler l'action implicite de la mise en œuvre ou d'autoriser sa poursuite. Dans le cas de l'hyperlien du navigateur, l'annulation de l'action se traduirait par la non-activation de l'hyperlien.
L'annulation est causée par l'appel de la méthode preventDefault
de l'interface
Event
. Si un ou plusieurs guetteurs
EventListener
appellent preventDefault
dans une phase quelconque
du flux d'événement, l'action implicite sera annulée.
Des mises en œuvre différentes définiront, le cas échéant, des actions implicites propres associées à chaque événement. Le DOM ne définit pas quelles sont ces actions.
L'interface EventTarget
est interprétée par tous les objets Node
d'une mise en œuvre
gérant le modèle d'événement du DOM. On peut donc obtenir cette interface en utilisant les
méthodes prépondérantes particulières de la liaison
sur une instance Node
. L'interface permet d'enregistrer ou de supprimer des guetteurs
EventListener
sur un objet EventTarget
et la distribution
d'événements à cet objet EventTarget
.
// Introduite dans DOM niveau 2 : interface EventTarget { void addEventListener(in DOMString type, in EventListener listener, in boolean useCapture); void removeEventListener(in DOMString type, in EventListener listener, in boolean useCapture); boolean dispatchEvent(in Event evt) raises(EventException); };
addEventListener
EventListener
à
une cible EventTarget
alors qu'elle traite un événement, ce guetteur ne sera pas déclenché par les actions courantes
mais pourra l'être lors d'une étape suivante du flux d'événement telle que dans la phase de bouillonnement.EventListener
identiques sont enregistrés,
avec les mêmes paramètres sur le même objet EventTarget
, les instances en double sont supprimées.
Ces instances ne provoquent pas d'appel en double du guetteur EventListener
et il n'est pas nécessaire de les supprimer en invoquant la méthode removeEventListener
puisqu'elles le sont déjà.
type
de type DOMString
listener
de type EventListener
listener
admet une interface définie par l'utilisateur qui contient les méthodes à appeler
quand l'événement advient.useCapture
de type boolean
true
, le paramètre useCapture
indique que l'utilisateur souhaite initier
une capture d'événement. À compter de cette initialisation, tous les événements du type défini seront distribués
au guetteur EventListener
enregistré
avant d'être distribués auprès des objets EventTarget
en aval dans l'arbre. Les événements bouillonnants en remontant
dans l'arbre ne déclencheront pas les guetteurs EventListener
prévus pour la capture.dispatchEvent
EventTarget
sur lequel la méthode dispatchEvent
est appelée.
evt
de type Event
|
La valeur de retour de la méthode |
removeEventListener
EventListener
d'une cible
EventTarget
alors qu'elle traite un événement, ce guetteur ne sera pas déclenché par les actions courantes.
On ne peut plus invoquer les guetteurs EventListener
après leur retrait.removeEventListener
avec des arguments ne permettant pas d'identifier un guetteur
EventListener
couramment enregistré sur l'objet
EventTarget
n'a aucun effet.
type
de type DOMString
EventListener
à retirer.listener
de type EventListener
listener
indique l'objet EventListener
à retirer.useCapture
de type boolean
EventListener
à retirer
a été enregistré comme guetteur capturant, ou non. Si un guetteur a été enregistré deux fois, l'un en capture et l'autre pas,
chacun doit être retiré séparément. Le retrait d'un guetteur capturant n'affecte pas une version non capturante du même guetteur,
et vice versa.L'interface EventListener
est la méthode principale pour la manipulation des événements.
L'utilisateur met en œuvre l'interface EventListener
et enregistre ses guetteurs sur un objet
EventTarget
en utilisant la méthode AddEventListener
.
L'utilisateur devrait retirer ses guetteurs EventListener
de
l'objet EventTarget
après qu'il a fini de les utiliser.
Quand un objet Node
est recopié en utilisant la méthode cloneNode
, les guetteurs
EventListener
attachés à l'objet Node
source ne le sont pas sur l'objet Node
copié.
Si l'utilisateur souhaite ajouter les mêmes guetteurs EventListener
à cette copie nouvellement créée,
il doit le faire manuellement.
// Introduite dans DOM niveau 2 : interface EventListener { void handleEvent(in Event evt); };
handleEvent
EventListener
.
Dans HTML 4.0, les guetteurs d'événement étaient définis comme attributs d'un élément. De ce fait,
l'enregistrement d'un autre guetteur d'événement du même type remplaçait le premier. Le modèle d'événement DOM
permet d'enregistrer plusieurs guetteurs sur une seule cible EventTarget
.
Pour cela, les guetteurs d'événement ne sont plus stockés comme valeurs d'attribut.
Pour une compatibilité avec HTML 4.0, les développeurs peuvent assimiler le paramétrage des attributs
représentant des gestionnaires d'événement à la création et l'enregistrement d'un guetteur EventListener
sur la cible EventTarget
.
La valeur implicite du paramètre useCapture
est false
. Ce guetteur
EventListener
se comporte de la même façon que n'importe quel autre
guetteur EventListener
susceptible d'être enregistré
sur la cible EventTarget
.
Si l'attribut représentant le guetteur d'événement est modifié, on peut le voir comme le retrait de l'ancien guetteur
EventListener
enregistré et
l'enregistrement d'un nouveau. Aucune technique n'est fournie qui permette aux guetteurs d'événement HTML 4.0
d'accéder aux données de contexte définies pour chaque événement.
L'interface Event
sert à fournir les données de contexte concernant un événement au gestionnaire qui le traite.
On transmet généralement l'objet qui met en œuvre l'interface Event
comme premier paramètre au gestionnaire d'événement.
Les informations de contexte plus spécifiques sont passées aux gestionnaires d'événements en dérivant de Event
d'autres interfaces qui contiennent les informations directement liées au type d'événement qu'elles accompagnent. Ces interfaces dérivées
sont également mises en œuvre par les objets transmis au guetteur d'événement.
// Introduite dans DOM niveau 2 : interface Event { // PhaseType const unsigned short CAPTURING_PHASE = 1; const unsigned short AT_TARGET = 2; const unsigned short BUBBLING_PHASE = 3; readonly attribute DOMString type; readonly attribute EventTarget target; readonly attribute EventTarget currentTarget; readonly attribute unsigned short eventPhase; readonly attribute boolean bubbles; readonly attribute boolean cancelable; readonly attribute DOMTimeStamp timeStamp; void stopPropagation(); void preventDefault(); void initEvent(in DOMString eventTypeArg, in boolean canBubbleArg, in boolean cancelableArg); };
Un entier indiquant la phase du flux d'événement du traitement en cours.
AT_TARGET
EventTarget
cible.BUBBLING_PHASE
CAPTURING_PHASE
bubbles
de type boolean
,
en lecture seuletrue
,
sinon false
.cancelable
de type boolean
,
en lecture seuletrue
,
sinon false
.currentTarget
de type EventTarget
,
en lecture seuleEventTarget
dont le traitement des guetteurs EventListener
est en cours.
Cela est particulièrement utile pendant la capture et le bouillonnement.eventPhase
de type unsigned short
,
en lecture seuletarget
de type EventTarget
,
en lecture seuleEventTarget
vers laquelle
l'événement a été distribué à l'origine.timeStamp
de type DOMTimeStamp
, en lecture seuletimeStamp
n'est peut-être pas disponible
pour tous les événements. Auquel cas, la valeur 0 sera retournée. Comme exemple de temps d'époque, celui du démarrage du système
ou encore le 1er janvier 1970 UTC 00:00:00.type
de type DOMString
,
en lecture seuleinitEvent
initEvent
sert à initialiser la valeur d'un objet Event
créé au travers de l'interface DocumentEvent
.
On ne peut appeler cette méthode qu'avant la distribution de Event
via la méthode dispatchEvent
,
quoiqu'on puisse l'appeler plusieurs fois pendant cette phase si nécessaire. Si on l'appelle plusieurs fois,
la dernière invocation prime. Si on l'appelle à partir
d'une sous-classe de Event
, seules les valeurs définies dans la méthode initEvent
sont modifiées,
et tous les autres attributs restent inchangés.
eventTypeArg
de type DOMString
canBubbleArg
de type boolean
cancelableArg
de type boolean
preventDefault
preventDefault
pour indiquer que l'événement doit être annulé, c'est-à-dire que toute action implicite entreprise normalement
par la mise en œuvre en conséquence de l'événement ne devra pas se produire.
Si, pendant une étape du flux d'événement, on appelle la méthode preventDefault
,
l'événement est annulé. Toute action implicite associée à l'événement ne se produira pas. Pour un événement non annulable,
l'appel de cette méthode n'a aucun effet. Une fois la méthode preventDefault
appelée, elle restera active pour le restant
de la propagation de l'événement. On peut appeler cette méthode à n'importe quelle étape du flux d'événement.
stopPropagation
stopPropagation
sert à empêcher la propagation ultérieure d'un événement pendant
le flux d'événement. Si un guetteur EventListener
appelle cette méthode,
l'événement cessera de se propager dans l'arbre. La distribution de l'événement à tous les guetteurs se terminera sur l'objet
EventTarget
courant, avant l'interruption du flux d'événement.
Cette méthode peut servir à toute étape du flux d'événement.
L'exploitation des événements peut produire un objet EventException
comme indiqué dans les descriptions de leurs méthodes.
// Introduite dans DOM niveau 2 : exception EventException { unsigned short code; }; // EventExceptionCode const unsigned short UNSPECIFIED_EVENT_TYPE_ERR = 0;
Un entier indiquant le type d'erreur généré.
UNSPECIFIED_EVENT_TYPE_ERR
Event
n'a pas été défini en initialisant
l'événement avant l'appel de la méthode. La valeur null
ou une chaîne vide pour le type de Event
déclenchera également cette exception.L'interface DocumentEvent
fournit un mécanisme au moyen duquel l'utilisateur peut créer un objet Event
d'un type reconnu par la mise en œuvre. On attend d'une mise en œuvre reconnaissant le modèle d'événement
qu'elle interprète l'interface DocumentEvent
sur le même objet que celui qui interprète l'interface Document
.
// Introduite dans DOM niveau 2 : interface DocumentEvent { Event createEvent(in DOMString eventType) raises(DOMException); };
createEvent
eventType
de type DOMString
eventType
définit le type de l'interface Event
à créer.
Si l'interface Event
définie est reconnue par
la mise en œuvre, cette méthode retournera une nouvelle instance Event
du type d'interface demandé. Si Event
doit être distribué
via la méthode dispatchEvent
, on doit appeler la méthode d'initialisation d'événement appropriée après la création
afin d'initialiser les valeurs de l'objet Event
.
Comme exemple, un utilisateur souhaitant synthétiser un objet de type UIEvent
appellerait la méthode createEvent
avec le paramètre "UIEvents". On peut alors appeler la méthode initUIEvent
sur l'objet UIEvent
nouvellement créé afin de définir le
type particulier d'objet UIEvent
à distribuer et ses données de contexte.createEvent
pour créer des objets Event
lorsqu'il n'est pas pratique ni nécessaire que l'utilisateur le fasse lui-même. Au cas où l'objet
Event
fourni par la mise en œuvre serait insuffisant,
l'utilisateur peut fournir ses propres interprétations de l'objet Event
à utiliser avec la méthode dispatchEvent
.
|
NOT_SUPPORTED_ERR : Soulevée si la mise en œuvre ne reconnaît pas le type d'interface
|
Le modèle d'événement DOM niveau 2 permet à une mise en œuvre DOM de prendre en charge plusieurs modules d'événements. Le modèle est conçu pour autoriser l'ajout de nouveaux modules d'événements à la demande. Le DOM n'essayera pas de définir tous les événements possibles. Pour les besoins de l'interopérabilité, le DOM définira un module d'événements de l'interface utilisateur, qui comprend des événements de bas niveau dépendant de l'appareil, un module d'événements logiques de l'interface utilisateur et un module d'événements de mutation des documents. Aucun nouveau type d'événement défini par un tiers ne peut commencer par la chaîne "DOM", qu'elle soit en minuscules, en majuscules ou un mélange des deux. Ce préfixe est réservé aux futurs modules d'événements du DOM. On recommande aussi fortement aux tiers qu'ils ajoutent des événements en utilisant leurs propres préfixes afin d'empêcher les confusions et de réduire les risques de conflits avec d'autres événements.
Le module d'événements de l'interface utilisateur se compose des événements listés dans HTML 4.0 et d'autres événements reconnus par les navigateurs DOM niveau 0.
Une application DOM peut employer la méthode hasFeature(feature, version)
de l'interface DOMImplementation
, respectivement avec les valeurs de paramètre "UIEvents" et "2.0",
afin de déterminer si le module d'événements de l'interface utilisateur est reconnu ou non par la mise en œuvre.
Pour la gestion complète de ce module, une mise en œuvre doit également gérer les fonctionnalités "Events",
définie dans cette spécification, et "Views", définie dans la spécification des vues DOM niveau 2
[DOM niveau 2 Views].
Pour d'autres renseignements, consulter la section à propos de la
conformité →vf
dans la spécification du DOM niveau 2 Core [DOM niveau 2 Core].
Remarque : Pour créer une instance de l'interface UIEvent
,
employer la chaîne de fonctionnalité "UIEvents" comme valeur du paramètre d'entrée à utiliser avec la méthode createEvent
de l'interface DocumentEvent
.
L'interface UIEvent
fournit les données de contexte spécifiques associées aux événements de l'interface utilisateur.
// Introduite dans DOM niveau 2 : interface UIEvent : Event { readonly attribute views::AbstractView view; readonly attribute long detail; void initUIEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in views::AbstractView viewArg, in long detailArg); };
initUIEvent
initUIEvent
sert à initialiser la valeur d'un objetUIEvent
créé
au travers de l'interface DocumentEvent
. On ne peut appeler cette méthode
qu'avant la distribution de l'objet UIEvent
via la méthode dispatchEvent
, quoiqu'on puisse l'appeler
plusieurs fois pendant cette phase si nécessaire. Si on l'appelle plusieurs fois, la dernière invocation prime.
typeArg
de type DOMString
canBubbleArg
de type boolean
cancelableArg
de type boolean
viewArg
de type views::AbstractView
AbstractView
de l'objet Event
.detailArg
de type long
Event
.Les différents types de ces événements qui peuvent se produire sont :
EventTarget
reçoit l'attention, par exemple via un
dispositif de pointage déplacé sur un élément
ou via une navigation par tabulation vers l'élément. À la différence de l'événement HTML focus, l'événement DOMFocusIn
est applicable à tout objet EventTarget
capable
de recevoir l'attention, et pas seulement aux commandes de formulaire
d'un élément FORM.
EventTarget
perd l'attention, par exemple via un dispositif de pointage déplacé en-dehors d'un élément ou via
une navigation par tabulation quittant l'élément. À la différence de l'événement HTML blur, l'événement DOMFocusOut
est applicable à tout objet EventTarget
capable
de recevoir l'attention, et pas seulement aux commandes de formulaire d'un élément FORM.
Le module d'événements de souris se compose des événements listés dans HTML 4.0 et d'autres événements gérés par les navigateurs DOM niveau 0. Ce module d'événements est conçu spécifiquement pour une utilisation avec les dispositifs d'entrée avec une souris.
Une application DOM peut employer la méthode hasFeature(feature, version)
de l'interface DOMImplementation
, respectivement avec les valeurs de paramètre "MouseEvents" et "2.0",
pour déterminer si le module d'événements de souris est reconnu ou non par la mise en œuvre.
Pour la gestion complète de ce module, une mise en œuvre doit également gérer la fonctionnalité "UIEvents"
définie dans cette spécification.
Pour d'autres renseignements, consulter la section à propos de la
conformité
→vf
dans la spécification du DOM niveau 2 Core [DOM niveau 2 Core].
Remarque : Pour créer une instance de l'interface MouseEvent
,
employer la chaîne de fonctionnalité "MouseEvents" comme valeur du paramètre d'entrée à utiliser avec la méthode createEvent
de l'interface DocumentEvent
.
L'interface MouseEvent
fournit des données de contexte spécifiques associées aux événements de souris.
L'attribut detail
hérité de l'objet UIEvent
indique le nombre de fois où le bouton d'une souris a été pressé et relâché sur un même endroit de l'écran
au cours d'une action de l'utilisateur. La valeur de l'attribut est 1 quand l'utilisateur commence cette action et s'incrémente d'une unité
à chaque cycle complet de pression-relaxation. Si l'utilisateur déplace la souris entre le clic et la relaxation,
la valeur est remise à 0 traduisant une absence de clic.
Dans le cas d'éléments imbriqués, les événements de souris sont toujours adressés à l'élément imbriqué le plus profondément. Les ancêtres de l'élément visé peuvent se servir du bouillonnement pour obtenir la notification des événements de souris qui adviennent sur leurs éléments descendants.
// Introduite dans DOM niveau 2 : interface MouseEvent : UIEvent { readonly attribute long screenX; readonly attribute long screenY; readonly attribute long clientX; readonly attribute long clientY; readonly attribute boolean ctrlKey; readonly attribute boolean shiftKey; readonly attribute boolean altKey; readonly attribute boolean metaKey; readonly attribute unsigned short button; readonly attribute EventTarget relatedTarget; void initMouseEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in views::AbstractView viewArg, in long detailArg, in long screenXArg, in long screenYArg, in long clientXArg, in long clientYArg, in boolean ctrlKeyArg, in boolean altKeyArg, in boolean shiftKeyArg, in boolean metaKeyArg, in unsigned short buttonArg, in EventTarget relatedTargetArg); };
altKey
de type boolean
,
en lecture seulebutton
de type unsigned short
,
en lecture seulebutton
sert à indiquer quel bouton de la souris a changé d'état.
Les valeurs de button
sont : 0 pour indiquer le bouton gauche de la souris, 1 pour indiquer, le cas échéant,
le bouton du milieu et 2 pour indiquer le bouton de droite. En ce qui concerne les souris configurées pour les gauchers,
les actions sur les boutons sont inversées et les valeurs se lisent de droite à gauche.clientX
de type long
,
en lecture seuleclientY
de type long
,
en lecture seulectrlKey
de type boolean
,
en lecture seulemetaKey
de type boolean
,
en lecture seulerelatedTarget
de type EventTarget
,
en lecture seuleEventTarget
secondaire
lié à un événement de l'interface utilisateur. Actuellement, cet attribut est utilisé avec l'événement mouseover pour désigner la cible
EventTarget
quitté par le dispositif de pointage
et avec l'événement mouseout pour désigner la cible EventTarget
où est entré le dispositif de pointage.screenX
de type long
,
en lecture seulescreenY
de type long
,
en lecture seuleshiftKey
de type boolean
,
en lecture seuleinitMouseEvent
initMouseEvent
sert à initialiser la valeur de l'objet MouseEvent
créé au travers de l'interface DocumentEvent
. On ne peut appeler cette méthode
qu'avant la distribution de l'objet MouseEvent
via la méthode dispatchEvent
, quoiqu'on puisse
l'appeler plusieurs fois pendant cette phase si nécessaire. Si on l'appelle plusieurs fois, la dernière invocation prime.
typeArg
de type DOMString
canBubbleArg
de type boolean
cancelableArg
de type boolean
viewArg
de type views::AbstractView
AbstractView
de l'objet Event
.detailArg
de type long
Event
.screenXArg
de type long
Event
à l'écran.screenYArg
de type long
Event
à l'écran.clientXArg
de type long
Event
sur le client.clientYArg
de type long
Event
sur le client.ctrlKeyArg
de type boolean
Event
.altKeyArg
de type boolean
Event
.shiftKeyArg
de type boolean
Event
.metaKeyArg
de type boolean
Event
.buttonArg
de type unsigned short
Event
.relatedTargetArg
de type EventTarget
EventTarget
en relation avec
l'objet Event
.Les différents types d'événement de souris qui peuvent advenir sont :
mousedown mouseup click
detail
s'incrémente à chaque cycle. Cet événement s'applique à la plupart des éléments.
EventTarget
duquel le dispositif de pointage sort.EventTarget
où entre le dispositif de pointage).La spécification des événements du DOM niveau 2 ne propose pas de module d'événements de touche. Un module d'événements conçu pour l'utilisation des dispositifs d'entrée au clavier sera inclus dans une version ultérieure de la spécification DOM.
Le module d'événements de mutation est conçu pour permettre la notification de tout changement intervenant dans la structure d'un document, y compris les modifications des objets Attr et Text. On peut remarquer qu'aucun des événements de mutation listés n'est prévu pour être annulable. Cela provient du fait qu'il est très difficile d'utiliser les interfaces DOM existantes, lesquelles conduisent à des modifications du document si un changement est exercé ou non sur le document à la suite de l'annulation de l'événement qui en est la cause. Bien que cette fonctionnalité reste souhaitable, il a été décidé de la laisser de côté tant que les transactions n'ont pas été ajoutées au DOM.
Beaucoup de modifications simples de l'arbre peuvent provoquer le lancement de plusieurs événements de mutation. Au lieu d'essayer de définir l'ordre d'apparition des événements de mutation, cette tâche est laissée à la mise en œuvre en raison de toutes les modifications possibles de l'arbre.
Une application DOM peut employer la méthode hasFeature(feature, version)
de l'interface DOMImplementation
, respectivement avec les valeurs de paramètre "MutationEvents" et "2.0",
pour déterminer si le module d'événements de mutation est reconnu ou non par la mise en œuvre. Pour la gestion complète de ce module,
une mise en œuvre doit également gérer la fonctionnalité "Events" définie dans cette spécification.
Pour d'autres renseignements, consulter la section à propos de la
conformité →vf
dans la spécification du DOM niveau 2 Core [DOM niveau 2 Core].
Remarque : Pour créer une instance de l'interface MutationEvent
,
employer la chaîne de fonctionnalité "MutationEvents" comme valeur du paramètre d'entrée à utiliser avec la méthode
createEvent
de l'interface DocumentEvent
.
L'interface MutationEvent
fournit les données de contexte spécifiques associées aux événements de mutation.
// Introduite dans DOM niveau 2 : interface MutationEvent : Event { // attrChangeType const unsigned short MODIFICATION = 1; const unsigned short ADDITION = 2; const unsigned short REMOVAL = 3; readonly attribute Node relatedNode; readonly attribute DOMString prevValue; readonly attribute DOMString newValue; readonly attribute DOMString attrName; readonly attribute unsigned short attrChange; void initMutationEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in Node relatedNodeArg, in DOMString prevValueArg, in DOMString newValueArg, in DOMString attrNameArg, in unsigned short attrChangeArg); };
Un entier indiquant de quelle façon l'objet Attr
a changé.
ADDITION
Attr
a juste été ajouté.MODIFICATION
Attr
a été modifié en place.REMOVAL
Attr
a juste été retiré.attrChange
de type unsigned short
,
en lecture seuleattrChange
indique le type de changement qui a initié l'événement DOMAttrModified
.
Les valeurs peuvent être MODIFICATION
, ADDITION
ou REMOVAL
.attrName
de type DOMString
,
en lecture seuleattrName
indique le nom du nœud Attr
modifié dans un événement DOMAttrModified
.newValue
de type DOMString
,
en lecture seulenewValue
indique la nouvelle valeur du nœud Attr
dans les événements DOMAttrModified
et du nœud CharacterData
dans les événements DOMCharacterDataModified
.prevValue
de type DOMString
,
en lecture seuleprevValue
indique la valeur précédente d'un nœud Attr
dans les
événements DOMAttrModified
et d'un nœud CharacterData
dans les événements DOMCharacterDataModified
.relatedNode
de type Node
,
en lecture seulerelatedNode
sert à identifier un nœud secondaire lié à un événement de mutation.
Par exemple, si un événement de mutation est distribué à un nœud pour lui signaler que son parent a changé,
l'attribut relatedNode
désigne ce parent. Par contre, si un événement est distribué à un sous-arbre pour lui signaler
qu'un de ses nœuds a changé, l'attribut relatedNode
désigne le nœud en question. Dans le cas
d'un événement DOMAttrModified
, l'attribut indique le nœud Attr
qui a été modifié, ajouté ou bien retiré.initMutationEvent
initMutationEvent
sert à initialiser la valeur de l'objet MutationEvent
créé au travers de l'interface DocumentEvent
. On ne peut appeler cette méthode
qu'avant la distribution de l'objet MutationEvent
via la méthode dispatchEvent
, quoiqu'on puisse l'appeler
plusieurs fois pendant cette phase si nécessaire. Si on l'appelle plusieurs fois, la dernière invocation prime.
typeArg
de type DOMString
canBubbleArg
de type boolean
cancelableArg
de type
boolean
relatedNodeArg
de type Node
Event
.prevValueArg
de type DOMString
prevValue
de l'objet Event
.
Sa valeur peut être null
.newValueArg
de type DOMString
newValue
de l'objet Event
.
Sa valeur peut être null
.attrNameArg
de type DOMString
attrName
de l'objet Event
.
Sa valeur peut être null
.attrChangeArg
de type unsigned short
attrChange
de l'objet Event
.Les différents types d'événement de mutation qui peuvent advenir sont :
relatedNode
contient le nœud parent.DOMNodeRemoved
sera lancé avant l'événement DOMNodeRemovedFromDocument
.
DOMNodeInserted
sera lancé
avant l'événement DOMNodeInsertedIntoDocument
.
Attr
a été modifié sur un nœud. La cible d'événement est le nœud
dont l'objet Attr
a changé. La valeur de l'attribut attrChange
indique si l'objet Attr
a été modifié, ajouté ou bien retiré. La valeur de l'attribut relatedNode
désigne le nœud Attr
dont la valeur a été affectée. Le remplacement littéral d'une valeur Attr
apparaît comme une modification du nœud Attr
, puisque son identité ne change pas. Par conséquent,
le remplacement du nœud Attr
par un nœud Attr
différent est interprété
comme le retrait du premier nœud Attr
et l'ajout du second.
CharacterData
dans un nœud a été modifié, sans que le nœud en question
n'ait été inséré ni retiré. Cet événement est lancé également par les modifications des éléments d'instruction de traitement.
La cible d'événement est le nœud CharacterData
.
Le module d'événements HTML se compose des événements listés dans HTML 4.0 et des autres événements reconnus par les navigateurs DOM niveau 0.
Une application DOM peut employer la méthode hasFeature(feature, version)
de l'interface DOMImplementation
, respectivement avec les valeurs de paramètre "HTMLEvents" et "2.0",
pour déterminer si le module d'événements HTML est reconnu ou non par la mise en œuvre.
Pour la gestion complète de ce module, une mise en œuvre doit également gérer la fonctionnalité "Events"
définie dans cette spécification. Pour d'autres renseignements, consulter la section à propos de la
conformité →vf
dans la spécification du DOM niveau 2 Core [DOM niveau 2 Core].
Remarque : Pour créer une instance de l'interface Event
pour le module d'événements HTML, employer la chaîne de fonctionnalité "HTMLEvents" comme valeur du paramètre d'entrée
à utiliser avec la méthode createEvent
de l'interface DocumentEvent
.
Les événements HTML utilisent l'interface de base Event du DOM pour transmettre une données de contexte.
Les différents types de ces événements qui peuvent advenir sont :