watch (méthode Object.watch)

Enregistre un gestionnaire d'événements à appeler lorsque la propriété spécifiée d'un objet ActionScript change. Lorsque la propriété est modifiée, le gestionnaire d'événements est appelé avec myObject comme objet contenant.

Vous pouvez utiliser l'instruction return dans la définition de votre méthode de rappel callback pour affecter la valeur de la propriété que vous observez. La valeur renvoyée par votre méthode de rappel callback est affectée à la propriété de l'objet observé. La valeur que vous choisissez de renvoyer diffère selon que vous souhaitez surveiller, modifier ou empêcher toute modification apportée à la propriété :

Si la méthode de rappel callback que vous définissez ne dispose pas d'instruction return la propriété de l'objet observé est définie sur une valeur undefined.

Un point d'observation peut filtrer (ou annuler) l'affectation de la valeur, en renvoyant un paramètre newval (ou oldval) modifié. Si vous supprimez une propriété pour laquelle un point d'observation a été défini, ce dernier ne disparaît pas. Si vous recréez la propriété ultérieurement, le point d'observation est toujours en vigueur. Pour supprimer un point d'observation, utilisez la méthode Object.unwatch.

Un seul point d'observation peut être enregistré sur une propriété. Les prochains appels de Object.watch() sur la même propriété remplacent le point d'observation d'origine.

La méthode Object.watch() se comporte de la même façon que la fonction Object.watch() à partir de JavaScript 1.2. La principale différence est liée au paramètre userData, qui est un ajout de Flash à Object.watch() que Netscape Navigator ne prend pas en charge. Vous pouvez transmettre le paramètre userData au gestionnaire d'événements et l'utiliser dans celui-ci.

La méthode Object.watch() ne peut pas observer les propriétés de lecture/définition. Les propriétés de lecture/définition fonctionnent par l'intermédiaire d'une évaluation " paresseuse " : la valeur de la propriété est déterminée lors de l'interrogation de la propriété. L'évaluation " paresseuse " est souvent efficace car la propriété n'est pas constamment mise à jour ; elle est évaluée en cas de besoin. Cependant, Object.watch() doit évaluer une propriété afin de déterminer s'il convient d'appeler la fonction de rappel callback. Pour pouvoir travailler avec une propriété de lecture/définition, Object.watch() doit évaluer la propriété en permanence, ce qui n'est pas efficace.

Généralement, les propriétés ActionScript prédéfinies, telles que _x, _y, _width, et _height, sont des propriétés de lecture/définition ne pouvant pas être observées par Object.watch().

Paramètres

callback:Function - Fonction à appeler lorsque la propriété observée change. Ce paramètre est un objet de fonction et non pas un nom de fonction exprimé en tant que chaîne. La forme de rappel callback est callback(prop, oldVal, newVal, userData).

userData:Object [facultatif] - Elément arbitraire des données ActionScript qui est transmis à la méthode callback. Si le paramètre userData est omis, undefined est transmis à la méthode callback.

Valeur renvoyée

Boolean - Valeur booléenne : true si le point d'observation a été créé avec succès, false dans tous les autres cas.

Exemple

L'exemple suivant utilise watch() pour vérifier si la propriété speed a une valeur supérieure à la limitation de vitesse :

// Crée un objet
var myObject:Object = new Object();

// Ajoute une propriété qui suit la vitesse
myObject.speed = 0;

// Fonction de rappel à exécuter si la propriété speed change
var speedWatcher:Function = function(prop, oldVal, newVal, speedLimit) {
    // Vérifie si la vitesse est au-dessus de la limite
    if (newVal > speedLimit) {
    trace ("You are speeding.");
    } 
    else {
    trace ("You are not speeding.");
    } 
    
    // Renvoie la valeur de newVal.
    return newVal;
}
// Utilisez watch() pour enregistrer le gestionnaire d'événements, 
// en effectuant la transmission sous forme de paramètres :
// - Le nom de la propriété à suivre : "speed"
// - Une référence à la fonction de rappel, speedWatcher
// - Limitation de vitesse à 55 en tant que paramètre userData
myObject.watch("speed", speedWatcher, 55);

// Définit la propriété speed sur 54, puis 57
myObject.speed = 54; // Renvoie : You are not speeding
myObject.speed = 57; // Renvoie : You are speeding

// Annule le suivi de l'objet
myObject.unwatch("speed");
myObject.speed = 54; // Il ne doit pas y avoir de sortie

watch (méthode Object.watch)

Paramètres

Valeur renvoyée

Exemple

Voir aussi