DOM:event
Un article de MDC.
Sommaire |
[modifier] Introduction
Ce chapitre décrit le modèle d'évènement du DOM Level 2 tel qu'implémenté par Gecko. L'interface Event elle-même est décrite, ainsi que les interfaces pour l'enregistrement des évènements sur d'autres nœuds du DOM, les gestionnaires et « écouteurs » (listeners) d'évènements, et quelques exemples plus longs montrant la manière dont les différentes interfaces d'évènements sont liées l'une à l'autre.
Il existe un très bon diagramme expliquant clairement les trois phases du parcours de event au travers de DOM dans le document DOM Level 3 Events draft (en).
[modifier] L'interface DOM Event
Les gestionnaires d'évènements peuvent être attachés à différents éléments dans le DOM. Lorsqu'un évènement se produit, un objet évènement est créé dynamiquement, et passé séquentiellement aux « écouteurs » d'évènements qui sont autorisés à gérer l'évènement. L'interface DOM Event est alors accessible par le gestionnaire de fonction, via l'objet évènement passé comme premier (et unique) argument.
L'exemple très simple ci-dessous montre la façon dont un objet event peut être référencé et manipulé depuis un tel gestionnaire d'évènement.
Notez qu'aucun paramètre « evt » n'est passé à la fonction ci-dessous. L'objet d'évènement est passé automatiquement à la fonction foo. Tout ce qu'il y a à faire est définir un paramètre dans le gestionnaire d'évènement pour recevoir cet objet.
function foo(evt) {
// les fonctions de gestion d'évènements comme celle-ci
// reçoivent une référence vers l'évènement géré
// (dans ce cas, la variable « evt »).
alert(evt);
}
table_el.onclick = foo;
Cet exemple est extrêmement simpliste, mais il montre une fonctionnalité importante des évènements dans le DOM Gecko, qui est qu'on accède typiquement aux objets event depuis les fonctions de gestion d'évènements. Une fois que vous avez une référence à l'objet event, vous pouvez accéder à toutes les propriétés et méthodes décrites dans ce chapitre.
Voir aussi l'exemple 5 : Propagation des évènements dans le chapitre Exemples pour un exemple plus détaillé de la façon dont les évènements se propagent dans le DOM.
[modifier] Liste des gestionnaires d'évènements DOM
En plus de l'objet event décrit ici, le DOM fournit également des méthodes pour enregistrer des écouteurs d'évènements (listeners) sur des nœuds du DOM, en enlever, et déclencher des évènements depuis le DOM. Celles-ci et les nombreux gestionnaires d'évènements sur les éléments HTML ou XML sont les points d'entrée principaux pour les évènements dans le DOM. Ces trois méthodes sont décrites dans la liste de la référence de DOM element.
Vous pouvez également passer la référence à l'objet event comme un paramètre prédéfini, appelé event, à la fonction de gestion de cet évènement. Cela ressemble très fort à la manière dont this fonctionne, mais pour des objets d'évènements plutôt que des références à des objets d'éléments.
<html>
<head>
<title>Exemple de paramètre d'objet "event"</title>
<script type="text/javascript">
function afficheCoords(evt){
alert(
"Valeur de clientX : " + evt.clientX + "\n" +
"Valeur de clientY : " + evt.clientY + "\n"
);
}
</script>
</head>
<body onmousedown="afficheCoords(event)">
<p>Pour afficher les coordonnées de la souris, cliquez n'importe où dans la page.</p>
</body>
</html>
L'utilisation du paramètre prédéfini de l'objet event vous permet de passer également d'autres paramètres au gestionnaire d'évènements DOM, si nécessaire :
<html>
<head>
<title>Pour afficher les coordonnées de la souris, cliquez n'importe où dans la page.</title>
<script type="text/javascript">
var par2 = 'hello';
var par3 = 'world!';
function afficheCoords(evt, p2, p3){
alert(
"Valeur de clientX : " + evt.clientX + "\n"
+ "Valeur de clientY : " + evt.clientY + "\n"
+ "p2 : " + p2 + "\n"
+ "p3 : " + p3 + "\n"
);
}
</script>
</head>
<body onmousedown="afficheCoords(event, par2, par3)">
<p>Pour afficher les coordonnées de la souris, cliquez n'importe où dans la page.</p>
</body>
</html>
[modifier] Propriétés
- event.altKey
- Renvoie une valeur booléenne indiquant si la touche
<alt>était enfoncée au cours de l'évènement. - event.bubbles
- Renvoie une valeur booléenne indiquant si l'évènement se propage vers le haut dans le DOM ou non.
- event.button
- Renvoie le bouton de la souris.
- event.cancelBubble
- Déprécié Renvoie une valeur booléenne indiquant si la propagation vers le haut de l'évènement a été annulée ou non.
- event.cancelable
- Renvoie une valeur booléenne indiquant si l'évènement est annulable.
- event.charCode
- Renvoie la valeur Unicode de la touche caractère qui a été enfoncée dans le cadre d'un évènement keypress.
- event.clientX
- Renvoie la position horizontale de l'évènement.
- event.clientY
- Renvoie la position verticale de l'évènement.
- event.ctrlKey
- Renvoie une valeur booléenne indiquant si la touche
<ctrl>était enfoncée au cours de l'évènement. - event.currentTarget
- Renvoie une référence vers la cible actuellement enregistrée pour l'évènement.
- event.detail
- Renvoie des détails concernant l'évènement, selon le type d'évènement.
- event.eventPhase
- Utilisée pour indiquer dans quelle phase de l'évènement on se trouve actuellement.
- event.explicitOriginalTarget
- La cible explicite originale de l'évènement (spécifique à Mozilla).
- event.isChar
- Renvoie une valeur booléenne indiquant si l'évènement a produit une touche de caractère ou non.
- event.keyCode
- Renvoie la valeur Unicode de toute touche non caractère dans un évènement keypress ou de toute touche dans les autres types d'évènement clavier.
- event.layerX
- Renvoie la coordonnée horizontale de l'évènement, relativement au calque courant.
- event.layerY
- Renvoie la coordonnée verticale de l'évènement, relativement au calque courant.
- event.metaKey
- Renvoie une valeur booléenne indiquant si la touche
metaétait enfoncée lors de l'évènement. - event.originalTarget
- La cible originale de l'évènement, avant toute modification de celle-ci (spécifique à Mozilla).
- event.pageX
- Renvoie la coordonnée horizontale de l'évènement relativement à la page.
- event.pageY
- Renvoie la coordonnée verticale de l'évènement relativement à la page.
- event.relatedTarget
- Identifie une cible secondaire pour l'évènement.
- event.screenX
- Renvoie la position horizontale de l'évènement sur l'écran.
- event.screenY
- Renvoie la position verticale de l'évènement sur l'écran.
- event.shiftKey
- Renvoie une valeur booléenne indiquant si la touche
<shift>était enfoncée lors du déclenchement de l'évènement. - event.target
- Renvoie une référence à la cible vers laquelle l'évènement était originellement destiné.
- event.timeStamp
- Renvoie le moment de création de l'évènement.
- event.type
- Renvoie le nom de l'évènement (insensible à la casse).
- event.view
- Identifie l'
AbstractViewdont est originaire l'évènement. - event.which
- Renvoie la valeur Unicode de la touche dans un évènement clavier, qu'elle soit ou non un caractère.
[modifier] Méthodes
- event.initEvent
- Initialise la valeur d'un objet
Eventcréé via l'interfaceDocumentEvent. - event.initKeyEvent
- Initialise un évènement clavier. Spécifique à Gecko.
- event.initMouseEvent
- Initialise la valeur d'un évènement souris une fois qu'il a été créé.
- event.initUIEvent
- Initialise un évènement UI (interface utilisateur) une fois qu'il a été créé.
- event.preventDefault
- Annule l'évènement (s'il est annulable).
- event.preventBubble
- Obsolète Empêche l'évènement de se propager. Cette méthode est déconseillée en faveur de la méthode standard stopPropagation et a été retirée dans Gecko 1.9.
- event.preventCapture
- Obsolète Cette méthode est déconseillée en faveur de la méthode standard stopPropagation et a été retirée dans Gecko 1.9.
- event.stopPropagation
- Arrête la propagation ultérieure d'évènements dans le DOM.