Event

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).

L'interface DOM `Event`

L'interface DOM <code>event</code> est exposée dans les objets <code>event</code> qui sont passés aux gestionnaires d'évènements sur divers éléments du DOM.

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.

Given that we don't list the three ways right here, the sentence is unclear, and is not perfectly right either IMO. -Nickolay There are three ways to attach an event listener to an element. With 2 of those techniques, the event object is passed to the handler function implicitly. The remaining technique requires you to specify the <code>event</code> object as a parameter, which is passed explicitly to the event handler function. 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 fonctionfoo . 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.

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>

Propriétés

event.bubbles: Renvoie une valeur booléenne indiquant si l'évènement se propage vers le haut dans le DOM ou non.
event.cancelable: Renvoie une valeur booléenne indiquant si l'évènement est annulable.
event.currentTarget: Renvoie une référence vers la cible actuellement enregistrée pour l'évènement.
event.defaultPrevented
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.originalTarget: La cible originale de l'évènement, avant toute modification de celle-ci (spécifique à Mozilla).
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'AbstractView dont 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.

Méthodes

event.initEvent: Initialise la valeur d'un objet Event créé via l'interface DocumentEvent.
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: 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: 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.