Flash Lite 2

Guide de référence du langage ActionScript Flash Lite 2.x > Classes ActionScript > Object > addProperty (méthode Object.addProperty)

addProperty (méthode Object.addProperty)

Crée une propriété de lecture/définition. Lorsque Flash lit une propriété de lecture/définition, il appelle la fonction de lecture get et la valeur renvoyée par la fonction devient la valeur de name. Lorsque Flash écrit une propriété de lecture/définition, il appelle la fonction de définition set et transmet la nouvelle valeur comme paramètre. Si une propriété portant le nom donné existe déjà, la nouvelle propriété la remplace.

Une fonction de « lecture » est une fonction sans paramètre. La valeur renvoyée peut être de n'importe quel type. Son type peut changer d'une invocation à l'autre. La valeur renvoyée est considérée comme la valeur actuelle de la propriété.

Une fonction de « définition » est une fonction qui prend un paramètre, qui correspond à la nouvelle valeur de la propriété. Par exemple, si la propriété x est affectée par l'instruction x = 1, le paramètre 1 du numéro de type est transmis à la fonction de définition. La valeur renvoyée par la fonction de définition est ignorée.

Vous pouvez ajouter des propriétés de lecture/définition à des objets prototypes. Dans ce cas, toutes les occurrences d'objet qui héritent de l'objet prototype héritent de la propriété de lecture/définition. Cela permet d'ajouter une propriété de lecture/définition à un emplacement, au niveau de l'objet prototype, et de la propager à toutes les occurrences d'une classe, tout comme lorsque vous ajoutez des méthodes à des objets prototypes. Si une fonction de lecture/définition est invoquée pour une propriété de lecture/définition dans un objet prototype hérité, la référence transmise à la fonction de lecture/définition sera l'objet originellement référencé et non l'objet prototype.

En cas d'appel incorrect, Object.addProperty() risque d'échouer et de provoquer une erreur. Le tableau suivant décrit les erreurs qui risquent de se produire :

Disponibilité : ActionScript 1.0 ; Flash Lite 2.0 - Avec les classes ActionScript 2.0, vous pouvez utiliser get ou set à la place de cette méthode.

Paramètres

name:String - Chaîne ; nom de la propriété d'objet à créer.

getter:Function - Fonction appelée pour récupérer la valeur de la propriété ; ce paramètre est un objet Function.

setter:Function - Fonction appelée pour définir la valeur de la propriété ; ce paramètre est un objet Function. Si vous transmettez la valeur null pour ce paramètre, la propriété est en lecture seule.

Valeur renvoyée

Boolean - Une valeur booléenne : true si la propriété a été créée correctement ; false dans tous les autres cas.

Exemple

Dans l'exemple suivant, un objet comporte deux méthodes internes, setQuantity() et getQuantity(). Une propriété, bookcount, permet d'appeler ces méthodes lorsqu'elle est définie ou récupérée. Une troisième méthode, getTitle(), renvoie une valeur en lecture seule qui est associée à la propriété bookname. Lorsqu'un script récupère la valeur de myBook.bookcount, l'interpréteur ActionScript appelle automatiquement myBook.getQuantity(). Lorsqu'un script modifie la valeur de myBook.bookcount, l'interpréteur appelle myObject.setQuantity(). La propriété bookname ne spécifie pas une fonction de définition set. Les tentatives de modification bookname sont donc ignorées.

function Book() {
    this.setQuantity = function(numBooks:Number):Void {
    this.books = numBooks;
    };
    this.getQuantity = function():Number {
    return this.books;
    };
    this.getTitle = function():String {
    return "Catcher in the Rye";
    };
    this.addProperty("bookcount", this.getQuantity, this.setQuantity);
    this.addProperty("bookname", this.getTitle, null);
}
var myBook = new Book();
myBook.bookcount = 5;
trace("You ordered "+myBook.bookcount+" copies of "+myBook.bookname);
// Renvoie : You ordered 5 copies of Catcher in the Rye

L'exemple précédent est fonctionnel, mais les propriétés bookcount et bookname sont ajoutées à chaque occurrence de l'objet Book, ce qui implique deux propriétés pour chaque occurrence de l'objet. Si la classe comporte de nombreuses propriétés, telles que bookcount et bookname,, ces propriétés risquent de consommer beaucoup de mémoire. Une alternative consiste à ajouter les propriété à Book.prototype pour que les propriétés bookcount et bookname n'existent qu'en un seul emplacement. L'effet obtenu est toutefois identique à celui du code dans l'exemple où bookcount et bookname étaient directement ajoutés à chaque occurrence. Si vous tentez d'accéder à l'une de ces propriétés dans une occurrence de Book, l'absence de la propriété entraîne le chaînage de prototype jusqu'à ce que les versions définies dans Book.prototype soient détectées. L'exemple suivant indique comment ajouter les propriétés à Book.prototype:

function Book() {}
Book.prototype.setQuantity = function(numBooks:Number):Void {
    this.books = numBooks;
};
Book.prototype.getQuantity = function():Number {
    return this.books;
};
Book.prototype.getTitle = function():String {
    return "Catcher in the Rye";
};
Book.prototype.addProperty("bookcount", Book.prototype.getQuantity, Book.prototype.setQuantity);
Book.prototype.addProperty("bookname", Book.prototype.getTitle, null);
var myBook = new Book();
myBook.bookcount = 5;
trace("You ordered "+myBook.bookcount+" copies of "+myBook.bookname);

L'exemple suivant indique comment utiliser les fonctions de lecture/définition implicites qui sont disponibles dans ActionScript 2.0. Au lieu de définir la fonction Book et modifier Book.prototype, définissez la classe Book dans un fichier externe appelé Book.as. Le code suivant doit figurer dans un fichier externe distinct appelé Book.as qui ne contient que cette définition de classe et figure dans le chemin de classe de l'application Flash :

class Book {
    var books:Number;
    function set bookcount(numBooks:Number):Void {
    this.books = numBooks;
    } 
    function get bookcount():Number {
    return this.books;
    } 
    function get bookname():String {
    return "Catcher in the Rye";
    } 
}

Le code suivant peut ensuite être placé dans un fichier FLA et fonctionner de la même façon que dans les exemples précédents :

var myBook:Book = new Book(); 
myBook.bookcount = 5;
trace("You ordered "+myBook.bookcount+" copies of "+myBook.bookname);

Voir aussi

Instruction get, Instruction set