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);
};
addEventListenerEventListener à
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 DOMStringlistener de type EventListenerlistener admet une interface définie par l'utilisateur qui contient les méthodes à appeler
quand l'événement advient.useCapture de type booleantrue, 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.dispatchEventEventTarget sur lequel la méthode dispatchEvent est appelée.
evt de type Event|
|
La valeur de retour de la méthode |
removeEventListenerEventListener 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 DOMStringEventListener à retirer.listener de type EventListenerlistener indique l'objet EventListener
à retirer.useCapture de type booleanEventListener à 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);
};
handleEventEventListener.
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_TARGETEventTarget cible.BUBBLING_PHASECAPTURING_PHASEbubbles 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 seuleinitEventinitEvent 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 DOMStringcanBubbleArg de type booleancancelableArg de type booleanpreventDefaultpreventDefault
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.
stopPropagationstopPropagation 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_ERREvent 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);
};
createEventeventType de type DOMStringeventType 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);
};
initUIEventinitUIEvent 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 DOMStringcanBubbleArg de type booleancancelableArg de type booleanviewArg de type views::AbstractViewAbstractView de l'objet Event.detailArg de type longEvent.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 seuleinitMouseEventinitMouseEvent 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 DOMStringcanBubbleArg de type booleancancelableArg de type booleanviewArg de type views::AbstractViewAbstractView de l'objet Event.detailArg de type longEvent.screenXArg de type longEvent à l'écran.screenYArg de type longEvent à l'écran.clientXArg de type longEvent sur le client.clientYArg de type longEvent sur le client.ctrlKeyArg de type booleanEvent.altKeyArg de type booleanEvent.shiftKeyArg de type booleanEvent.metaKeyArg de type booleanEvent.buttonArg de type unsigned shortEvent.relatedTargetArg de type EventTargetEventTarget 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é.
ADDITIONAttr a juste été ajouté.MODIFICATIONAttr a été modifié en place.REMOVALAttr 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é.initMutationEventinitMutationEvent 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 DOMStringcanBubbleArg de type booleancancelableArg de type
booleanrelatedNodeArg de type NodeEvent.prevValueArg de type DOMStringprevValue de l'objet Event.
Sa valeur peut être null.newValueArg de type DOMStringnewValue de l'objet Event.
Sa valeur peut être null.attrNameArg de type DOMStringattrName de l'objet Event.
Sa valeur peut être null.attrChangeArg de type unsigned shortattrChange 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 :