| (\s* [^>]* >)) .*? <\/p> /gix Si l’indicateur x est défini et que vous souhaitez établir une correspondance avec un espace vide, faites précéder l’espace vide d’une barre oblique. Par exemple, les deux expressions régulières suivantes sont équivalentes : /foo bar/ /foo \ bar/x La propriété lastIndex La propriété lastIndex spécifie la position d’index dans la chaîne à laquelle la recherche suivante doit démarrer. Cette propriété affecte les méthodes exec() et test() appelées sur une expression régulière dont l’indicateur g est défini sur true. Considérons par exemple le code qui suit : var pattern:RegExp = /p\w*/gi; var str:String = "Pedro Piper picked a peck of pickled peppers."; trace(pattern.lastIndex); var result:Object = pattern.exec(str); while (result != null) { trace(pattern.lastIndex); result = pattern.exec(str); } La propriété lastIndex est défini sur 0 par défaut (pour commencer les recherches au début de la chaîne). Après chaque correspondance, elle est définie sur la position d’index suivant la correspondance. Par conséquent, le résultat pour le code précédent est le suivant : 0 5 11 18 25 36 44 Si l’indicateur global est défini sur false, les méthodes exec() et test() n’utilisent pas ni ne définissent la propriété lastIndex. Les méthodes match(), replace() et search() de la classe String lancent toutes les recherches du début de la chaîne, indépendamment du réglage de la propriété lastIndex de l’expression régulière utilisée dans l’appel à la méthode (néanmoins, la méthode match() définit lastIndex sur 0). Vous pouvez définir la propriété lastIndex de sorte à ajuster la position de début dans la chaîne pour la mise en correspondance des expressions régulières. La propriété source La propriété source spécifie la chaîne qui définit la portion de modèle d’une expression régulière. Exemple : GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 93 Utilisation d’expressions régulières Dernière mise à jour le 27/4/2013 var pattern:RegExp = /foo/gi; trace(pattern.source); // foo Méthodes d’utilisation d’expressions régulières avec des chaînes Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe RegExp comprend deux méthodes : exec() et test(). Outre les méthodes exec() et test() de la classe RegExp, la classe String comprend les méthodes suivantes qui vous permettent d’établir une correspondance avec des expressions régulières dans des chaînes : match(), replace(), search() et splice(). La méthode test() Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La méthode test() de la classe RegExp vérifie si la chaîne fournie contient une correspondance pour l’expression régulière, comme l’indique l’exemple suivant : var pattern:RegExp = /Class-\w/; var str = "Class-A"; trace(pattern.test(str)); // output: true La méthode exec() Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La méthode exec() de la classe RegExp vérifie si la chaîne fournie contient une correspondance pour l’expression régulière et renvoie un tableau avec les éléments suivants : • La sous-chaîne correspondante • Les correspondances de sous-chaîne pour les groupes entre parenthèses dans l’expression régulière Le tableau inclut également une propriété index qui indique la position d’index du début de la correspondance de sous-chaîne. Considérons par exemple le code qui suit : var pattern:RegExp = /\d{3}\-\d{3}-\d{4}/; //U.S phone number var str:String = "phone: 415-555-1212"; var result:Array = pattern.exec(str); trace(result.index, " - ", result); // 7-415-555-1212 Utilisez la méthode exec() plusieurs fois pour établir une correspondance avec plusieurs sous-chaînes lorsque l’indicateur g (global) est défini pour l’expression régulière : GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 94 Utilisation d’expressions régulières Dernière mise à jour le 27/4/2013 var pattern:RegExp = /\w*sh\w*/gi; var str:String = "She sells seashells by the seashore"; var result:Array = pattern.exec(str); while (result != null) { trace(result.index, "\t", pattern.lastIndex, "\t", result); result = pattern.exec(str); } //output: // 0 3 She // 10 19 seashells // 27 35 seashore Méthodes de chaîne utilisant des paramètres RegExp Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les méthodes suivantes de la classe String prennent des expressions régulières comme paramètres : match(), replace(), search() et split(). Pour plus d’informations sur ces méthodes, voir « Recherche de modèles dans des chaînes et remplacement de sous-chaînes » à la page 17. Exemple d’expression régulière : analyseur Wiki Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Cet exemple simple de conversion de texte Wiki illustre des utilisations d’expressions régulières : • Conversion de lignes de texte qui mettent en correspondance un modèle Wiki source et les chaînes de sortie HTML appropriées. • Utilisation d’une expression régulière pour convertir des modèles URL en balises de lien hypertexte HTML • Utilisation d’une expression régulière pour convertir les chaînes dollar américain ("$9.95", par exemple) en chaînes euro ("8.24 €", par exemple) Pour obtenir les fichiers d’application de cet exemple, voir www.adobe.com/go/learn_programmingAS3samples_flash_fr. Les fichiers de l’application WikiEditor se trouvent dans le dossier Samples/WikiEditor. L’application se compose des fichiers suivants : Fichier Description WikiEditor.mxml ou WikiEditor.fla Fichier d’application principal dans Flash (FLA) ou Flex (MXML). GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 95 Utilisation d’expressions régulières Dernière mise à jour le 27/4/2013 Définition de la classe WikiParser Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe WikiParser inclut des méthodes qui convertissent le texte d’entrée Wiki en sortie HTML équivalente. Il ne s’agit pas d’une application de conversion Wiki très puissante, mais elle illustre des utilisations d’expressions régulières pour la mise en correspondance de modèle et la conversion de chaîne. La fonction constructeur et la méthode setWikiData() initialisent un exemple de chaîne de texte d’entrée Wiki, comme suit : public function WikiParser() { wikiData = setWikiData(); } Lorsque l’utilisateur clique sur le bouton de test dans l’application exemple, cette dernière appelle la méthode parseWikiString() de l’objet WikiParser. Cette méthode appelle plusieurs autres méthodes, qui assemblent à leur tour la chaîne HTML résultante. public function parseWikiString(wikiString:String):String { var result:String = parseBold(wikiString); result = parseItalic(result); result = linesToParagraphs(result); result = parseBullets(result); return result; } Chaque méthode appelée—parseBold(), parseItalic(), linesToParagraphs(), et parseBullets()—utilise la méthode replace() de la chaîne pour remplacer les modèles de correspondance, définis par une expression régulière, de façon à transformer le texte Wiki en texte formaté HTML. Conversion des modèles de texte en gras et en italique La méthode parseBold() recherche un modèle de texte Wiki en gras ('''foo''', par exemple) et le transforme en son équivalent HTML (foo, par exemple), comme suit : private function parseBold(input:String):String { var pattern:RegExp = /'''(.*?)'''/g; return input.replace(pattern, "$1"); } com/example/programmingas3/regExpExamples/WikiParser.as Une classe qui comprend des méthodes utilisant des expressions régulières pour convertir des modèles de texte d’entrée Wiki en sortie HTML équivalente. com/example/programmingas3/regExpExamples/URLParser.as Une classe qui comprend des méthodes utilisant des expressions régulières pour convertir des chaînes URL en balises de lien hypertexte HTML . com/example/programmingas3/regExpExamples/CurrencyConverter.as Une classe qui comprend des méthodes utilisant des expressions régulières pour convertir des chaînes dollar américain en chaînes euro. Fichier Description GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 96 Utilisation d’expressions régulières Dernière mise à jour le 27/4/2013 Notez que la portion (.?*) de l’expression régulière correspond à des caractères (*) entre les deux modèles de définition '''. Le quantificateur ? rend la correspondance nongreedy, de façon à ce que pour une chaîne telle que '''aaa''' bbb '''ccc''', la première chaîne mise en correspondance soit '''aaa''' et non la chaîne entière (qui commence et se termine par le modèle '''). Les parenthèses dans l’expression régulière définissent un groupe capturé, et la méthode replace() se réfère à ce groupe en utilisant le code $1 dans la chaîne de remplacement. L’indicateur g (global) dans l’expression régulière vérifie que la méthode replace() remplace toutes les correspondances dans la chaîne (pas simplement la première). La méthode parseItalic() fonctionne comme la méthode parseBold(), sauf qu’elle recherche deux apostrophes ('') comme séparateur pour le texte en italique (au lieu de trois) : private function parseItalic(input:String):String { var pattern:RegExp = /''(.*?)''/g; return input.replace(pattern, "$1"); } Conversion de modèles de puce Comme dans l’exemple suivant, la méthode parseBullet() recherche le modèle de puce Wiki (* foo, par exemple) et le transforme en son équivalent HTML (

. Ces lignes dans la méthode extraient des lignes vides de la chaîne d’entrée Wiki : var pattern:RegExp = /^$/gm; var result:String = input.replace(pattern, ""); Les symboles ^ et $ dans l’expression régulière correspondent au début et à la fin d’une ligne. L’indicateur m (multiline) dans l’expression régulière fait en sorte que cette dernière compare le symbole ^ au début d’une ligne, et non simplement au début de la chaîne. La méthode replace() remplace toutes les chaînes de correspondance (lignes vides) par une chaîne vide (""). L’indicateur g (global) dans l’expression régulière vérifie que la méthode replace() remplace toutes les correspondances dans la chaîne (pas simplement la première). GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 97 Utilisation d’expressions régulières Dernière mise à jour le 27/4/2013 Conversion d’URL en balises HTML Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lorsque l’utilisateur clique sur le bouton de test dans l’exemple d’application et qu’il a coché la case urlToATag, l’application appelle la méthode statique URLParser.urlToATag() pour convertir les chaînes URL de la chaîne Wiki d’entrée en balises HTML . var protocol:String = "((?:http|ftp)://)"; var urlPart:String = "([a-z0-9_-]+\.[a-z0-9_-]+)"; var optionalUrlPart:String = "(\.[a-z0-9_-]*)"; var urlPattern:RegExp = new RegExp(protocol + urlPart + optionalUrlPart, "ig"); var result:String = input.replace(urlPattern, "$1$2$3"); La fonction constructeur RegExp() sert à assembler une expression régulière (urlPattern) à partir de plusieurs parties constituantes. Ces parties constituantes sont représentées par chaque chaîne définissant une partie du modèle de l’expression régulière. La première partie du modèle de l’expression régulière, définie par la chaîne protocol, définit un protocole URL : http:// ou ftp://. Les parenthèses définissent un groupe non capturé, indiqué par le symbole ?. Ceci signifie que les parenthèses servent simplement à définir un groupe pour le modèle de permutation | ; le groupe ne correspondra pas à des codes de backreference ($1, $2, $3) dans la chaîne de remplacement de la méthode replace(). Les autres parties constituantes de l’expression régulière utilisent chacune des groupes capturés (indiqués par des parenthèses dans le modèle) qui sont ensuite utilisés dans les codes de backreference ($1, $2, $3) dans la chaîne de remplacement de la méthode replace(). La partie du modèle définie par la chaîne urlPart correspond au moins à l’un des caractères suivants : a-z, 0-9, _ ou -. La quantificateur + indique qu’au moins un caractère a une correspondance. Le \. indique un point obligatoire (.). Et le reste correspond à une autre chaîne d’au moins un de ces caractères : a-z, 0-9, _ ou -. La partie du modèle définie par la chaîne optionalUrlPart correspond à zéro ou plus des caractères suivants : un point (.) suivi par n’importe quel nombre de caractères alphanumériques (y compris _ et -). Le quantificateur * indique que zéro ou plus de caractères ont une correspondance. L’appel à la méthode replace() utilise l’expression régulière et assemble la chaîne HTML de remplacement, à l’aide de backreferences. La méthode urlToATag() appelle ensuite la méthode emailToATag(), qui utilise des techniques semblables pour remplacer des modèles de courrier électronique par des chaînes de lien hypertexte HTML . Les expressions régulières utilisées pour correspondre à des URL HTTP, FTP et de courrier électronique dans le fichier sont assez simples car elles sont données à titre d’exemple. Elles sont beaucoup plus compliquées si l’on souhaite établir une correspondance plus correcte. Conversion des chaînes dollar américain en chaînes euro Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lorsque l’utilisateur clique sur le bouton de test dans l’exemple d’application et qu’il a coché la case dollarToEuro , l’application appelle la méthode statique CurrencyConverter.usdToEuro() pour convertir des chaînes dollar américain ("$9.95", par exemple) en chaînes euro ("8.24€", par exemple), comme suit : var usdPrice:RegExp = /\$([\d,]+.\d+)+/g; return input.replace(usdPrice, usdStrToEuroStr); GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 98 Utilisation d’expressions régulières Dernière mise à jour le 27/4/2013 La première ligne définit un modèle simple pour établir une correspondance avec des chaînes dollar américain. Le caractère $ est précédé du caractère d’échappement (\). La méthode replace() utilise l’expression régulière pour établir une correspondance avec le modèle et appelle la fonction usdStrToEuroStr() pour déterminer la chaîne de remplacement (une valeur en euros). Lorsqu’un nom de fonction est utilisé comme deuxième paramètre de la méthode replace(), les éléments suivants sont transmis comme paramètres à la fonction appelée : • La partie correspondante de la chaîne. • Tout groupe entre parenthèses capturé correspondant. Le nombre d’arguments transmis de cette façon varie selon le nombre de correspondances de groupes entre parenthèses capturées. Pour déterminer le nombre de correspondances de groupes entre parenthèses capturés, vérifiez arguments.length - 3 dans le code de la fonction. • La position d’index dans la chaîne où débute la correspondance. • La chaîne complète. La méthode usdStrToEuroStr() convertit les modèles de chaîne dollar américain en chaînes euro, comme suit : private function usdToEuro(...args):String { var usd:String = args[1]; usd = usd.replace(",", ""); var exchangeRate:Number = 0.828017; var euro:Number = Number(usd) * exchangeRate; trace(usd, Number(usd), euro); const euroSymbol:String = String.fromCharCode(8364); // € return euro.toFixed(2) + " " + euroSymbol; } args[1] représente le groupe entre parenthèses capturé mis en correspondance par l’expression régulière usdPrice. Il s’agit de la portion numérique de la chaîne dollar américain, c’est-à-dire la quantité en dollar, sans le signe $. La méthode applique une conversion de taux de change et renvoie la chaîne résultante (avec un symbole de fin de ligne € au lieu du symbole $ placé à gauche). 99 Dernière mise à jour le 27/4/2013 Chapitre 6 : Utilisation de XML Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures ActionScript 3.0 inclut un groupe de classes basé sur la spécification ECMAScript pour XML (E4X) (ECMA-357 version 2). Ces classes comprennent une fonctionnalité puissante et facile à utiliser permettant de travailler avec des données XML. A l’aide d’E4X, vous pouvez développer un code avec des données XML plus rapidement qu’avec les techniques de programmation précédentes. En outre, le code que vous produisez est plus facile à lire. Voir aussi Classe XML Spécification ECMA-357 Principes de base de XML Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures XML est un moyen standard de représenter des informations structurées afin de permettre aux ordinateurs de les utiliser facilement et aux utilisateurs de les écrire et de les comprendre. XML est l’abréviation de eXtensible Markup Language. La norme XML est disponible à l’adresse www.w3.org/XML/. XML offre une façon pratique et standard de classer des données, afin de faciliter leur lecture, leur accès et leur manipulation. XML utilise une arborescence et une structure de balises identiques à celle du code HTML. Voici un exemple simple de données XML : Steve and the flubberblubs 1989 2006-10-17-08:31 Les données XML peuvent également être plus complexes, avec des balises imbriquées dans d’autres balises ainsi que des attributs et d’autres composants structurels. Voici un exemple plus complexe de données XML : GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 100 Utilisation de XML Dernière mise à jour le 27/4/2013 Steve and the flubberblubs 1989 Steve and the flubberblubs 2006-10-17-08:31 Steve and the flubberblubs 2006-10-17-08:35 Steve and the flubberblubs 2006-10-17-08:39 Steve and the flubberblubs 2006-10-17-08:44 Vous remarquerez que ce document XML contient d’autres structures XML complètes (les balises song avec leurs enfants, par exemple). Il démontre également d’autres structures XML telles que des attributs (tracknumber et length dans les balises song), et des balises qui contiennent d’autres balises au lieu de données (la balise tracks, par exemple). Prise en main de XML Si vous avez peu ou pas d’expérience avec XML, voici une brève description des aspects les plus courants des données XML. Les données XML sont écrites sous forme de texte brut, avec une syntaxe spécifique permettant d’organiser les informations en un format structuré. Généralement, un seul jeu de données XML est appelé un document XML. Dans le format XML, les données sont organisées en éléments (qui peuvent être des éléments de données uniques ou des conteneurs pour d’autres éléments) à l’aide d’une structure hiérarchique. Chaque document XML possède un élément comme niveau supérieur ou élément principal. Cet élément racine peut contenir une seule information, même s’il est plus probable qu’il contienne d’autres éléments qui, à leur tour, contiennent d’autres éléments, et ainsi de suite. Par exemple, ce document XML contient les informations relatives à un album musical : Steve and the flubberblubs Happy 2006-10-17-08:31 Chaque élément se distingue par un ensemble de balises—le nom de l’élément placé entre chevrons (signes inférieur à et supérieur à). La balise de début, indiquant le début de l’élément, porte le nom de l’élément : GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 101 Utilisation de XML Dernière mise à jour le 27/4/2013 Si un élément est vide, il peut être écrit comme élément vide (parfois appelé élément de fin automatique). Dans XML, cet élément : est identique à cet élément : Outre le contenu de l’élément placé entre les balises de début et de fin, un élément peut comporter d’autres valeurs, appelées attributs, définies dans la balise de début de l’élément. Par exemple, cet élément XML définit un seul attribut appelé length, avec la valeur "4:19" : Chaque élément XML possède un contenu qui est soit une valeur, soit un ou plusieurs éléments XML, ou rien du tout (pour un élément vide). En savoir plus sur XML Pour en savoir plus sur l’utilisation de XML, un grand nombre de livres et de ressources sont disponibles, ainsi que les sites Web suivants : • Didacticiel XML W3Schools : http://w3schools.com/xml/ • Didacticiels XMLpitstop, listes de discussions, etc. : http://xmlpitstop.com/ Classes ActionScript pour utiliser XML ActionScript 3.0 inclut plusieurs classes permettant d’utiliser des informations structurées XML. Les deux classes principales sont les suivantes : • XML : représente un seul élément XML, qui peut être un document XML avec plusieurs enfants ou un élément à une seule valeur dans un document. • XMLList : représente un ensemble d’éléments XML. Un objet XMLList est utilisé lorsque plusieurs éléments XML sont des frères (au même niveau, et contenus par le même parent, dans la hiérarchie du document XML). Par exemple, une occurrence de XMLList serait le moyen le plus facile d’utiliser cet ensemble d’éléments XML (probablement contenus dans un document XML): Fred Wilson James Schmidt Susan Harriet Thurndon Pour des utilisations plus avancées impliquant des espaces de noms XML, ActionScript inclut également les classes Namespace et QName. Pour plus d’informations, voir « Utilisation des espaces de noms XML » à la page 114. Outre les classes intégrées permettant d’utiliser XML, ActionScript 3.0 comprend également plusieurs opérateurs offrant des fonctionnalités spécifiques pour accéder et manipuler des données XML. Cette approche d’utilisation de XML au moyen de ces classes et de ces opérateurs est appelée ECMAScript pour XML (E4X), comme défini par la spécification ECMA-357 version 2. Concepts importants et terminologie La liste de référence suivante contient des termes importants utilisés dans le cadre de la programmation de routines de gestion des éléments XML : Elément Entité unique dans un document XML correspondant au contenu compris entre une balise de début et une balise de fin (balises comprises). Les éléments XML peuvent contenir des données de texte ou d’autres éléments, ou bien être vides. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 102 Utilisation de XML Dernière mise à jour le 27/4/2013 Elément vide Elément XML qui ne contient aucun élément enfant. Les éléments vides sont souvent écrits en tant que balises de fin automatique (, par exemple). Document Structure XML unique. Un document XML peut contenir n’importe quel nombre d’éléments (ou peut être constitué d’un seul élément vide) ; cependant, un document XML doit avoir un seul élément de niveau supérieur qui contient tous les autres éléments dans le document. Noeud Autre nom d’un élément XML. Attribut Valeur nommée associée à un élément qui est écrite dans la balise de début de l’élément au format attributename="valeur", plutôt que d’être écrite comme élément enfant séparé imbriqué dans l’élément. Approche E4X concernant le traitement XML Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La spécification ECMAScript pour XML définit un ensemble de classes et de fonctionnalités permettant d’utiliser des données XML. Cet ensemble de classes et de fonctionnalités est connu sous le nom de E4X. ActionScript 3.0 intègre les classes E4X suivantes : XML, XMLList, QName et Namespace. Les méthodes, propriétés et opérateurs des classes E4X sont conçus avec les objectifs suivants : • Simplicité : lorsque cela est possible, E4X facilite l’écriture et la compréhension du code à utiliser avec des données XML. • Cohérence : les méthodes et le raisonnement E4X sont cohérents avec eux-mêmes et avec d’autres parties d’ActionScript. • Connaissance : vous manipulez des données XML avec des opérateurs bien connus tels que l’opérateur point (.). Remarque : ActionScript 2.0 intègre une autre classe XML. Dans ActionScript 3.0, cette classe a été renommée XMLDocument, pour éviter tout conflit de nom avec la classe XML d’ActionScript 3.0 qui fait partie d’E4X. Dans ActionScript 3.0, les classes héritées (XMLDocument, XMLNode, XMLParser et XMLTag) sont comprises dans le package flash.xml, pour la prise en charge du contenu hérité principalement. Les nouvelles classes E4X sont des classes de base. Vous ne devez pas importer de package pour les utiliser. Pour plus d’informations sur les classes XML d’ActionScript 2.0 existantes, voir le package flash.xml dans le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash. Voici un exemple de manipulation de données avec E4X : var myXML:XML = burger 3.95 fries 1.45 Votre application charge souvent des données XML depuis une source externe telle qu’un service Web ou un flux RSS. Toutefois, par souci de clarté, les exemples de code ci-après affectent les données XML en tant que littéraux. Comme l’indique le code suivant, E4X inclut des opérateurs intuitifs tels que les opérateurs point (.) et identifiant d’attribut (@) pour accéder aux propriétés et aux attributs dans l’XML : GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 103 Utilisation de XML Dernière mise à jour le 27/4/2013 trace(myXML.item[0].menuName); // Output: burger trace(myXML.item.(@id==2).menuName); // Output: fries trace(myXML.item.(menuName=="burger").price); // Output: 3.95 Utilisez la méthode appendChild() pour affecter un nouveau noeud enfant à l’XML, comme l’indique le code suivant : var newItem:XML = medium cola 1.25 myXML.appendChild(newItem); Utilisez les opérateurs @ et. non seulement pour lire des données mais également pour les affecter, comme dans l’exemple suivant : myXML.item[0].menuName="regular burger"; myXML.item[1].menuName="small fries"; myXML.item[2].menuName="medium cola"; myXML.item.(menuName=="regular burger").@quantity = "2"; myXML.item.(menuName=="small fries").@quantity = "2"; myXML.item.(menuName=="medium cola").@quantity = "2"; Utilisez une boucle for pour parcourir en boucle les noeuds de l’XML, comme suit : var total:Number = 0; for each (var property:XML in myXML.item) { var q:int = Number(property.@quantity); var p:Number = Number(property.price); var itemTotal:Number = q * p; total += itemTotal; trace(q + " " + property.menuName + " $" + itemTotal.toFixed(2)) } trace("Total: $", total.toFixed(2)); Objets XML Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Un objet XML peut représenter un élément XML, un attribut, un commentaire, une instruction de traitement ou un élément de texte. Un objet XML est classé soit dans la catégorie des objets ayant un contenu simple, soit dans celle des objets ayant un contenu complexe. Un objet XML ayant des noeuds enfant est considéré comme ayant un contenu complexe. Le contenu est considéré comme simple s’il correspond à un attribut, un commentaire, une instruction de traitement ou un noeud de texte. Par exemple, l’objet XML suivant contient un contenu complexe, y compris un commentaire et une instruction de traitement : GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 104 Utilisation de XML Dernière mise à jour le 27/4/2013 XML.ignoreComments = false; XML.ignoreProcessingInstructions = false; var x1:XML = burger 3.95 fries 1.45 Comme l’indique l’exemple suivant, vous pouvez maintenant utiliser les méthodes comments() et processingInstructions() pour créer des objets XML, un commentaire et une instruction de traitement : var x2:XML = x1.comments()[0]; var x3:XML = x1.processingInstructions()[0]; Propriétés XML Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe XML a cinq propriétés statiques : • Les propriétés ignoreComments et ignoreProcessingInstructions déterminent si les commentaires ou les instructions de traitement sont ignorés lorsque l’objet XML est analysé. • La propriété ignoreWhitespace détermine si les espaces blancs sont ignorés dans les balises d’un élément et les expressions intégrées séparées uniquement par des espaces blancs. • Les propriétés prettyIndentet prettyPrinting servent à formater le texte renvoyé par les méthodes toString() et toXMLString() de la classe XML. Pour plus d’informations sur ces propriétés, voir le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash. Méthodes XML Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les méthodes suivantes vous permettent d’utiliser la structure hiérarchique des objets XML : • appendChild() • child() • childIndex() • children() • descendants() • elements() • insertChildAfter() GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 105 Utilisation de XML Dernière mise à jour le 27/4/2013 • insertChildBefore() • parent() • prependChild() Les méthodes suivantes vous permettent d’utiliser des attributs d’objet XML : • attribute() • attributes() Les méthodes suivantes vous permettent d’utiliser des propriétés d’objet XML : • hasOwnProperty() • propertyIsEnumerable() • replace() • setChildren() Les méthodes suivantes vous permettent d’utiliser des espaces de nom et des noms qualifiés : • addNamespace() • inScopeNamespaces() • localName() • name() • namespace() • namespaceDeclarations() • removeNamespace() • setLocalName() • setName() • setNamespace() Les méthodes suivantes vous permettent d’utiliser et de déterminer certains types de contenu XML : • comments() • hasComplexContent() • hasSimpleContent() • nodeKind() • processingInstructions() • text() Les méthodes suivantes vous permettent d’effectuer des conversions en chaînes et de formater des objets XML : • defaultSettings() • setSettings() • settings() • normalize() • toString() • toXMLString() GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 106 Utilisation de XML Dernière mise à jour le 27/4/2013 Il existe quelques méthodes supplémentaires : • contains() • copy() • valueOf() • length() Pour plus d’informations sur ces méthodes, voir le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash. Objets XMLList Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Une occurrence de XMLList représente un ensemble arbitraire d’objets XML. Elle peut contenir des documents XML complets, des fragments XML ou les résultats d’une requête XML. Les méthodes suivantes vous permettent d’utiliser la structure hiérarchique des objets XMLList : • child() • children() • descendants() • elements() • parent() Les méthodes suivantes vous permettent d’utiliser des attributs d’objet XMLList : • attribute() • attributes() Les méthodes suivantes vous permettent d’utiliser des propriétés XMLList : • hasOwnProperty() • propertyIsEnumerable() Les méthodes suivantes vous permettent d’utiliser et de déterminer certains types de contenu XML : • comments() • hasComplexContent() • hasSimpleContent() • processingInstructions() • text() Les méthodes suivantes vous permettent d’effectuer des conversions en chaînes et de formater les objets XMLList : • normalize() • toString() • toXMLString() GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 107 Utilisation de XML Dernière mise à jour le 27/4/2013 Il existe quelques méthodes supplémentaires : • contains() • copy() • length() • valueOf() Pour plus d’informations sur ces méthodes, voir le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash. Pour un objet XMLList qui contient exactement un élément XML, vous pouvez utiliser toutes les propriétés et les méthodes de la classe XML car un XMLList avec un élément XML est traité comme un objet XML. Par exemple, dans le code suivant, étant donné que doc.div est un objet XMLList contenant un élément, vous pouvez utiliser la méthode appendChild() de la classe XML : var doc:XML =

Hello, Bob.

Hello.

Hello, Bob.

Hello.

Hello, Bob.

Hello.

Hello, Bob.

Hello.

; var x2:XML = ; Conversion de type XML Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous pouvez convertir des objets XML et XMLList en valeurs String. De même, vous pouvez convertir des chaînes en objets XML et XMLList. Sachez que toutes les valeurs d’attribut, les noms et les valeurs de texte XML sont des chaînes. Les sections suivantes décrivent toutes ces formes de conversion de type XML. Conversion d’objets XML et XMLList en chaînes Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les classes XML et XMLList contiennent les méthodes toString() et toXMLString(). La méthode toXMLString() renvoie une chaîne qui comprend la totalité des balises, des attributs, des déclarations d’espace de nom et du contenu de l’objet XML. Pour les objets XML ayant un contenu complexe (éléments enfant), la méthode toString() procède exactement comme la méthode toXMLString(). Pour les objets XML ayant un contenu simple (ceux qui contiennent un seul élément de texte), la méthode toString() renvoie uniquement le contenu de texte de l’élément, comme indiqué dans l’exemple suivant : var myXML:XML = burger 3.95 ; trace(myXML.item[0].menuName.toXMLString()); // burger trace(myXML.item[0].menuName.toString()); // burger GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 116 Utilisation de XML Dernière mise à jour le 27/4/2013 Si vous utilisez la méthode trace() sans spécifier toString() ou toXMLString(), les données sont converties à l’aide de la méthode toString() par défaut, comme indiqué dans le code suivant : var myXML:XML = burger 3.95 ; trace(myXML.item[0].menuName); // burger Lorsque vous utilisez la méthode trace() pour déboguer un code, vous pouvez utiliser la méthode toXMLString() de façon à ce que la méthode trace() génère des données plus complètes. Conversion de chaînes en objets XML Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous pouvez utiliser le constructeur new XML() pour créer un objet XML à partir d’une chaîne, comme suit : var x:XML = new XML("test"); Si vous tentez de convertir une chaîne en XML à partir d’une chaîne qui représente un XML non valide ou un XML qui n’est pas formé correctement, une erreur d’exécution est renvoyée, comme suit : var x:XML = new XML("test"); // throws an error Conversion de valeurs d’attribut, de noms et de valeurs de texte à partir de chaînes Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Toutes les valeurs d’attribut XML, les noms et les valeurs de texte sont des types de données String que vous pouvez convertir en d’autres types de données. Par exemple, le code suivant utilise la fonction Number() pour convertir des valeurs de texte en nombres : GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 117 Utilisation de XML Dernière mise à jour le 27/4/2013 var myXML:XML = 3.95 1.00 ; var total:XML = 0; myXML.appendChild(total); for each (var item:XML in myXML.item) { myXML.total.children()[0] = Number(myXML.total.children()[0]) + Number(item.price.children()[0]); } trace(myXML.total); // 4.95; Si ce code n’utilisait pas la fonction Number(), il interpréterait l’opérateur + comme l’opérateur de concaténation de chaîne, et la méthode trace() de la dernière ligne générerait les éléments suivants : 01.003.95 Lecture de documents XML externes Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous pouvez utiliser la classe URLLoader pour charger des données XML depuis une URL. Pour utiliser le code suivant dans vos applications, remplacez la valeur XML_URL dans l’exemple par une URL valide : import flash.events.Event; import flash.net.URLLoader; var myXML:XML = new XML(); var XML_URL:String = "http://www.example.com/Sample3.xml"; var myXMLURL:URLRequest = new URLRequest(XML_URL); var myLoader:URLLoader = new URLLoader(myXMLURL); myLoader.addEventListener(Event.COMPLETE, xmlLoaded); function xmlLoaded(event:Event):void { myXML = XML(myLoader.data); trace("Data loaded."); } Vous pouvez également utiliser la classe XMLSocket pour définir une connexion de socket XML asynchrone avec un serveur. Pour plus d’informations, voir le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 118 Utilisation de XML Dernière mise à jour le 27/4/2013 Utilisation de XML dans un exemple ActionScript : chargement de données RSS depuis Internet Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’exemple d’application RSSViewer présente plusieurs fonctions d’utilisation d’XML dans ActionScript, notamment : • Utilisation de méthodes XML pour parcourir des données XML sous la forme d’un flux RSS. • Utilisation de méthodes XML pour assembler des données XML sous la forme HTML à utiliser dans un champ de texte. Le format RSS est largement utilisé pour diffuser des nouvelles via XML. Un fichier de données RSS simple peut avoir l’aspect suivant : http://www.nws.noaa.gov/alerts/ak.html Alaska - Watches, Warnings and Advisories http://www.nws.noaa.gov/alerts/ak.html#A18.AJKNK.1900 Short Term Forecast Issued At: 2005-04-11T19:00:00 Expired At: 2005-04-12T01:00:00 Issuing Weather Forecast Office Homepage: http://pajk.arh.noaa.gov http://www.nws.noaa.gov/alerts/ak.html#AKZ019.AJKNOWAJK.190000 Short Term Forecast Issued At: 2005-04-11T19:00:00 Expired At: 2005-04-12T01:00:00 Issuing Weather Forecast Office Homepage: http://pajk.arh.noaa.gov L’application SimpleRSS lit les données RSS depuis Internet, analyse les données à la recherche de titres, de liens et de descriptions et renvoie ces données. La classe SimpleRSSUI fournit l’IU et appelle la classe SimpleRSS qui effectue le traitement XML. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 119 Utilisation de XML Dernière mise à jour le 27/4/2013 Pour obtenir les fichiers d’application de cet exemple, voir www.adobe.com/go/learn_programmingAS3samples_flash_fr. Les fichiers d’application RSSViewer se trouvent dans le dossier Samples/RSSViewer. L’application se compose des fichiers suivants : Lecture et analyse de données XML Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe RSSParser comprend une méthode xmlLoaded() qui convertit les données RSS d’entrée, stockées dans la variable rssXML, en une chaîne contenant une sortie formatée HTML, rssOutput. Vers le début de la méthode, le code définit l’espace de nom XML par défaut si les données RSS source comprennent un espace de nom par défaut : if (rssXML.namespace("") != undefined) { default xml namespace = rssXML.namespace(""); } Les lignes suivantes parcourent ensuite en boucle le contenu des données XML source, en examinant chaque propriété descendante appelée item : for each (var item:XML in rssXML..item) { var itemTitle:String = item.title.toString(); var itemDescription:String = item.description.toString(); var itemLink:String = item.link.toString(); outXML += buildItemHTML(itemTitle, itemDescription, itemLink); } Les trois premières lignes définissent simplement des variables de chaîne pour représenter les propriétés de titre, de description et de lien de la propriété item des données XML. La ligne suivante appelle la méthode buildItemHTML() pour obtenir des données HTML sous la forme d’un objet XMLList et utilise les trois nouvelles variables de chaîne en tant que paramètres. Fichier Description RSSViewer.mxml ou RSSViewer.fla Fichier d’application principal dans Flash (FLA) ou Flex (MXML). com/example/programmingas3/rssViewer/RSSParser.as Une classe qui contient des méthodes utilisant E4X pour parcourir des données (XML) RSS et générer une représentation HTML correspondante. RSSData/ak.rss Un exemple de fichier RSS. Cette application est définie pour lire des données RSS à partir du Web, sur un flux RSS Flex hébergé par Adobe. Néanmoins, vous pouvez facilement modifier l’application pour lire des données RSS depuis ce document qui utilise un schéma légèrement différent de celui du flux RSS Flex. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 120 Utilisation de XML Dernière mise à jour le 27/4/2013 Assemblage de données XMLList Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les données HTML (un objet XMLList) se présentent comme suit : itemTitle

itemDescription
More...

Les premières lignes de la méthode effacent l’espace de noms xml par défaut : default xml namespace = new Namespace(); La directive default xml namespace a un domaine de niveau bloc de fonction. Cela signifie que le domaine de cette déclaration est la méthode buildItemHTML(). Les lignes qui suivent assemblent l’objet XMLList en fonction des arguments de chaîne transmis à la fonction : var body:XMLList = new XMLList(); body += new XML("" + itemTitle + ""); var p:XML = new XML("

" + itemDescription + "

"); var link:XML = ; link.@href = itemLink; // link.font.@color = "#008000"; // // 0x008000 = green link.font = "More..."; p.appendChild(
); p.appendChild(link); body += p; Cet objet XMLList représente des données de chaîne adaptées à un champ de texte HTML d’ActionScript. La méthode xmlLoaded() utilise la valeur de renvoi de la méthode buildItemHTML() et la convertit en une chaîne : XML.prettyPrinting = false; rssOutput = outXML.toXMLString(); Extraction du titre du flux RSS et envoi d’un événement personnalisé Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La méthode xmlLoaded() définit une variable de chaîne rssTitle en fonction des informations contenues dans les données XML RSS source : rssTitle = rssXML.channel.title.toString(); Pour finir, la méthode xmlLoaded() génère un événement qui notifie l’application que les données sont analysées et disponibles : dataWritten = new Event("dataWritten", true); 121 Dernière mise à jour le 27/4/2013 Chapitre 7 : Utilisation de la fonctionnalité JSON native ActionScript 3.0 fournit une API native permettant de coder et de décoder des objets ActionScript à l’aide du format JavaScript Object Notation (JSON). La classe JSON et les fonctions membres associées suivent la spécification ECMA- 262 5e édition avec de légères variations. Le membre de la communauté Todd Anderson fournit une comparaison entre l’API JSON native et la classe JSON as3corelib tierce. Voir Working with Native JSON in Flash Player 11 (disponible en anglais uniquement). Voir aussi JSON Présentation de l’API JSON L’API JSON ActionScript est constituée de la classe JSON et des fonctions membres toJSON() sur quelques classes natives. Pour les applications nécessitant un codage JSON personnalisé pour une classe, la structure ActionScript propose diverses méthodes permettant de remplacer le codage par défaut. La classe JSON gère en interne l’importation et l’exportation des classes ActionScript qui ne fournissent pas de membre toJSON(). Dans ces cas, la classe JSON traverse les propriétés publiques de chaque objet qu’elle détecte. Si un objet contient d’autres objets, JSON parcourt les objets imbriqués et effectue la même traversée. Si un objet fournit une méthode toJSON(), JSON utilise cette méthode personnalisée plutôt que son algorithme interne. L’interface JSON est composée d’une méthode d’encodage, stringify(), et d’une méthode de décodage, parse(). Chacune de ces méthodes fournit un paramètre permettant d’insérer votre propre logique dans la procédure de codage et de décodage JSON. Pour stringify(), ce paramètre est appelé replacer ; pour parse(), il est appelé reviver. Ces paramètres prennent une définition de fonction avec deux arguments à l’aide de la signature suivante : function(k, v):* Méthodes toJSON() La signature des méthodes toJSON() est public function toJSON(k:String):* JSON.stringify() appelle la méthode toJSON(), si elle existe, pour chaque propriété publique qu’elle rencontre lorsqu’elle traverse un objet. Une propriété consiste en une paire clé-valeur. Lorsque stringify() appelle la méthode toJSON(), il transmet la clé, k, de la propriété qu’il examine actuellement. Une implémentation toJSON() standard évalue chaque nom de propriété et renvoie l’encodage souhaité de sa valeur. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 122 Utilisation de la fonctionnalité JSON native Dernière mise à jour le 27/4/2013 La méthode toJSON() peut renvoyer tout type de valeur (identifiée à l’aide du signe *) et pas uniquement une chaîne. Ce type de renvoi de variable permet à la méthode toJSON() de renvoyer un objet, le cas échéant. Par exemple, si une propriété de votre classe personnalisée contient un objet issu d’une autre bibliothèque tierce, vous pouvez renvoyer cet objet dès que la méthode toJSON() détecte votre propriété. JSON parcourt alors l’objet tiers. Le processus de codage est le suivant : • Si la méthode toJSON() renvoie un objet qui n’est pas évalué par rapport à une chaîne, stringify() parcourt cet objet. • Si la méthode toJSON() renvoie une chaîne, stringify() enveloppe la valeur dans une autre chaîne, renvoie la chaîne enveloppée et passe à la valeur suivante. Dans de nombreux cas, il est préférable de renvoyer un objet plutôt que de renvoyer une chaîne JSON créée par votre application. Le renvoi d’un objet implique l’utilisation de l’algorithme de codage JSON et permet à JSON de se répéter dans les objets imbriqués. La méthode toJSON() n’est pas définie dans la classe Object ou dans la plupart des autres classes natives. Son absence indique à JSON d’effectuer sa traversée standard sur les propriétés publiques de l’objet. Si vous préférez, vus pouvez également utiliser la méthode toJSON() pour exposer les propriétés privées de votre objet. Certaines classes natives posent néanmoins des problèmes que les bibliothèques ActionScript sont incapables de résoudre efficacement dans tous les cas d’utilisation. Pour ces classes, ActionScript fournit une implémentation triviale que le client peut à nouveau implémenter selon ses besoins. Les classes qui fournissent des membres toJSON() triviaux sont les suivantes : • ByteArray • Date • Dictionary • XML Vous pouvez intégrer la classe ByteArray dans une sous-classe pour remplacer sa méthode toJSON(), mais vous pouvez aussi redéfinir son prototype. Les classes Date et XML, qui sont déclarées comme étant finales, vous obligent à utiliser le prototype de classe pour redéfinir toJSON(). La classe Dictionary est déclarée comme étant dynamique, ce qui vous donne la liberté de remplacer la méthode toJSON(). Définition du comportement JSON personnalisé Vous disposez de plusieurs options pour implémenter vos propres codage et décodage JSON pour les classes natives : • Définir ou remplacer toJSON() sur la sous-classe personnalisée d’une classe native non finale • Définir et redéfinir toJSON() sur le prototype de la classe • Définir une propriété toJSON sur une classe dynamique • Utiliser les paramètres JSON.stringify() replacer et JSON.parser() reviver Voir aussi ECMA-262, 5e édition GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 123 Utilisation de la fonctionnalité JSON native Dernière mise à jour le 27/4/2013 Définition de la méthode toJSON() sur le prototype d’une classe intégrée L’implémentation JSON native dans ActionScript imite le mécanisme JSON ECMAScript défini dans ECMA-262, 5e édition. Etant donné qu’ECMAScript ne prend pas en charge les classes, ActionScript définit le comportement de JSON en termes de distribution basée sur les prototypes. Ancêtres des classes ActionScript 3.0, les prototypes permettent un héritage simulé, ainsi que les ajouts et redéfinitions de membres. ActionScript permet de définir ou de redéfinir toJSON() sur le prototype d’une classe. Ce privilège s’étend aux classes déclarées comme étant finales. Lorsque vous définissez toJSON() sur le prototype d’une classe, votre définition s’applique à toutes les occurrences de cette classe dans le cadre de votre application. Par exemple, voici comment vous pouvez définir une méthode toJSON() sur le prototype de la classe MovieClip : MovieClip.prototype.toJSON = function(k):* { trace("prototype.toJSON() called."); return "toJSON"; } Lorsque votre application appelle la méthode stringify() sur une occurrence de MovieClip, stringify()renvoie le résultat de votre méthode toJSON() : var mc:MovieClip = new MovieClip(); var js:String = JSON.stringify(mc); //"prototype toJSON() called." trace("js: " + js); //"js: toJSON" Vous pouvez en outre remplacer toJSON() dans les classes natives qui définissent cette méthode. Par exemple, le code suivant remplace Date.toJSON() : Date.prototype.toJSON = function (k):* { return "any date format you like via toJSON: "+ "this.time:"+this.time + " this.hours:"+this.hours; } var dt:Date = new Date(); trace(JSON.stringify(dt)); // "any date format you like via toJSON: this.time:1317244361947 this.hours:14" Définition ou remplacement de toJSON() au niveau de la classe Les applications n’ont pas toujours besoin d’utiliser des prototypes pour redéfinir toJSON(). Il est également possible de définir toJSON() en tant que membre d’une sous-classe si la classe parente n’est pas marquée comme finale. Vous pouvez par exemple étendre la classe ByteArray et définir une fonction toJSON() publique : GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 124 Utilisation de la fonctionnalité JSON native Dernière mise à jour le 27/4/2013 package { import flash.utils.ByteArray; public class MyByteArray extends ByteArray { public function MyByteArray() { } public function toJSON(s:String):* { return "MyByteArray"; } } } var ba:ByteArray = new ByteArray(); trace(JSON.stringify(ba)); //"ByteArray" var mba:MyByteArray = new MyByteArray(); //"MyByteArray" trace(JSON.stringify(mba)); //"MyByteArray" Si un classe est dynamique, il est possible d’ajouter une propriété toJSON à un objet de cette classe et de lui attribuer une fonction de la façon suivante : var d:Dictionary = new Dictionary(); trace(JSON.stringify((d))); // "Dictionary" d.toJSON = function(){return {c : "toJSON override."};} // overrides existing function trace(JSON.stringify((d))); // {"c":"toJSON override."} Vous pouvez remplacer, définir ou redéfinir toJSON() sur n’importe quelle classe ActionScript. Néanmoins, la plupart des classes ActionScript intégrées ne définissent pas toJSON(). La classe Object ne définit pas la méthode toJSON dans son prototype par défaut ni ne la déclare en tant que membre de classe. Seule une poignée de classes natives définit la méthode comme fonction prototype. C’est pourquoi, dans la plupart des cas, vous ne pouvez pas remplacer toJSON() de façon traditionnelle. Les classes natives qui ne définissent pas toJSON() sont sérialisées sur JSON par l’implémentation JSON interne. Dans la mesure du possible, évitez de remplacer cette fonctionnalité intégrée. Si vous définissez un membre toJSON(), la classe JSON utilise votre logique plutôt que sa propre fonctionnalité. Utilisation du paramètre replacer de la méthode JSON.stringify() Il peut être utile de remplacer toJSON() sur le prototype en vue de modifier le comportement d’exportation JSON d’une classe dans une application. Néanmoins, votre logique d’exportation doit s’appliquer uniquement à des cas spéciaux sous des conditions provisoires. Pour prendre en compte ces modifications à petite échelle, vous pouvez utiliser le paramètre replacer de la méthode JSON.stringify(). La méthode stringify() applique la fonction transmise via le paramètre replacer à l’objet en cours de codage. La signature pour cette fonction est similaire à celle de toJSON() : function (k,v):* GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 125 Utilisation de la fonctionnalité JSON native Dernière mise à jour le 27/4/2013 Contrairement à la méthode toJSON(), la fonction replacer requiert la valeur v, ainsi que la clé k. Cette différence est nécessaire, car la méthode stringify() est définie sur l’objet JSON statique et non sur l’objet en cours de codage. Lorsque la méthode JSON.stringify() appelle replacer(k,v), elle traverse l’objet d’entrée d’origine. Le paramètre implicite this transmis à la fonction replacer fait référence à l’objet qui détient la clé et la valeur. Etant donné que la méthode JSON.stringify() ne modifie pas l’objet d’entrée d’origine, cet objet reste inchangé dans le conteneur actuellement traversé. Vous pouvez par conséquent utiliser le code this[k] pour interroger la clé sur l’objet d’origine. Le paramètre v renferme la valeur que toJSON() convertit. Tout comme toJSON(), la fonction replacer peut renvoyer tout type de valeur. Si replacer renvoie une chaîne, le moteur JSON convertit le contenu en séquence d’échappement entre guillemets et place ce contenu également entre guillemets. Cette structure garantit que stringify() reçoive un objet de chaîne JSON valide qui reste une chaîne dans un prochain appel de JSON.parse(). Le code suivant utilise le paramètre replacer et le paramètre this implicite pour renvoyer les valeurs time et hours d’un objet Date : JSON.stringify(d, function (k,v):* { return "any date format you like via replacer: "+ "holder[k].time:"+this[k].time + " holder[k].hours:"+this[k].hours; }); Utilisation du paramètre reviver de la méthode JSON.parse() Le paramètre reviver de la méthode JSON.parse() est l’opposé de la fonction replacer : il convertit une chaîne JSON en objet ActionScript utilisable. L’argument reviver est une fonction qui prend deux paramètres et renvoie tout type : function (k,v):* Dans cette fonction, k est une clé et v est la valeur de k. Tout comme stringify(), parse() traverse les paires clévaleur JSON et applique la fonctionreviver, si elle existe, à chaque paire. L’un des problèmes potentiels est que la classe JSON ne renvoie pas le nom de classe ActionScript d’un objet. Il peut par conséquent être difficile de savoir quel type d’objet ranimer. Ce problème peut en outre s’avérer particulièrement délicat lorsque les objets sont imbriqués. En désignant les fonctions toJSON(), replacer et reviver, vous pouvez trouver des moyens d’identifier les objets ActionScript exportés tout en gardant intacts les objets d’origine. Exemple d’analyse L’exemple suivant illustre une stratégie de ranimation d’objets analysés à partir de chaînes JSON. Cet exemple définit deux classes : JSONGenericDictExample et JSONDictionaryExtnExample. La classe JSONGenericDictExample est une classe Dictionary personnalisée. Chaque enregistrement contient le nom et la date de naissance d’une personne, ainsi qu’un ID unique. Chaque fois que le constructeur JSONGenericDictExample est appelé, il ajoute l’objet nouvellement créé à un tableau statique interne avec un entier augmentant statiquement comme son ID. La classe JSONGenericDictExample définit également une méthode revive() qui extrait uniquement l’entier du membre id le plus long. La méthode revive() utilise cet entier pour rechercher et renvoyer l’objet ranimable adéquat. La classe JSONDictionaryExtnExample étend la classe Dictionary ActionScript. Ses enregistrements n’ont pas de structure définie et peuvent contenir toutes sortes de données. Les données sont attribuées après la construction de l’objet JSONDictionaryExtnExample et non par les propriétés définies dans la classe. Les enregistrements de JSONDictionaryExtnExample utilisent les objets JSONGenericDictExample comme clés. Lorsqu’un objet JSONDictionaryExtnExample est ranimé, la fonction JSONGenericDictExample.revive() utilise l’ID associé à JSONDictionaryExtnExample pour récupérer l’objet de clé correct. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 126 Utilisation de la fonctionnalité JSON native Dernière mise à jour le 27/4/2013 Plus important encore, la méthode JSONDictionaryExtnExample.toJSON() renvoie une chaîne de marqueurs en plus de l’objet JSONDictionaryExtnExample. Cette chaîne identifie la sortie JSON comme appartenant à la classe JSONDictionaryExtnExample. Ce marqueur indique clairement le type d’objet en cours de traitement lors de l’exécution de JSON.parse(). package { // Generic dictionary example: public class JSONGenericDictExample { static var revivableObjects = []; static var nextId = 10000; public var id; public var dname:String; public var birthday; public function JSONGenericDictExample(name, birthday) { revivableObjects[nextId] = this; this.id = "id_class_JSONGenericDictExample_" + nextId; this.dname = name; this.birthday = birthday; nextId++; } public function toString():String { return this.dname; } public static function revive(id:String):JSONGenericDictExample { var r:RegExp = /^id_class_JSONGenericDictExample_([0-9]*)$/; var res = r.exec(id); return JSONGenericDictExample.revivableObjects[res[1]]; } } } package { import flash.utils.Dictionary; import flash.utils.ByteArray; // For this extension of dictionary, we serialize the contents of the // dictionary by using toJSON public final class JSONDictionaryExtnExample extends Dictionary { public function toJSON(k):* { var contents = {}; for (var a in this) { contents[a.id] = this[a]; } // We also wrap the contents in an object so that we can // identify it by looking for the marking property "class E" // while in the midst of JSON.parse. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 127 Utilisation de la fonctionnalité JSON native Dernière mise à jour le 27/4/2013 return {"class JSONDictionaryExtnExample": contents}; } // This is just here for debugging and for illustration public function toString():String { var retval = "[JSONDictionaryExtnExample <"; var printed_any = false; for (var k in this) { retval += k.toString() + "=" + "[e="+this[k].earnings + ",v="+this[k].violations + "], " printed_any = true; } if (printed_any) retval = retval.substring(0, retval.length-2); retval += ">]" return retval; } } } Lorsque le script d’exécution suivant appelle JSON.parse() sur un objet JSONDictionaryExtnExample, la fonction reviver appelle JSONGenericDictExample.revive() sur chaque objet dans JSONDictionaryExtnExample. Cet appel extrait l’ID qui représente la clé de l’objet. La fonction JSONGenericDictExample.revive() utilise cet ID pour récupérer et renvoyer l’objet JSONDictionaryExtnExample stocké à partir d’un tableau statique privé. import flash.display.MovieClip; import flash.text.TextField; var a_bob1:JSONGenericDictExample = new JSONGenericDictExample("Bob", new Date(Date.parse("01/02/1934"))); var a_bob2:JSONGenericDictExample = new JSONGenericDictExample("Bob", new Date(Date.parse("05/06/1978"))); var a_jen:JSONGenericDictExample = new JSONGenericDictExample("Jen", new Date(Date.parse("09/09/1999"))); var e = new JSONDictionaryExtnExample(); e[a_bob1] = {earnings: 40, violations: 2}; e[a_bob2] = {earnings: 10, violations: 1}; e[a_jen] = {earnings: 25, violations: 3}; trace("JSON.stringify(e): " + JSON.stringify(e)); // {"class JSONDictionaryExtnExample": //{"id_class_JSONGenericDictExample_10001": //{"earnings":10,"violations":1}, //"id_class_JSONGenericDictExample_10002": //{"earnings":25,"violations":3}, //"id_class_JSONGenericDictExample_10000": // {"earnings":40,"violations":2}}} var e_result = JSON.stringify(e); var e1 = new JSONDictionaryExtnExample(); var e2 = new JSONDictionaryExtnExample(); // It's somewhat easy to convert the string from JSON.stringify(e) back // into a dictionary (turn it into an object via JSON.parse, then loop // over that object's properties to construct a fresh dictionary). GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 128 Utilisation de la fonctionnalité JSON native Dernière mise à jour le 27/4/2013 // // The harder exercise is to handle situations where the dictionaries // themselves are nested in the object passed to JSON.stringify and // thus does not occur at the topmost level of the resulting string. // // (For example: consider roundtripping something like // var tricky_array = [e1, [[4, e2, 6]], {table:e3}] // where e1, e2, e3 are all dictionaries. Furthermore, consider // dictionaries that contain references to dictionaries.) // // This parsing (or at least some instances of it) can be done via // JSON.parse, but it's not necessarily trivial. Careful consideration // of how toJSON, replacer, and reviver can work together is // necessary. var e_roundtrip = JSON.parse(e_result, / / This is a reviver that is focused on rebuilding JSONDictionaryExtnExample objects. function (k, v) { if ("class JSONDictionaryExtnExample" in v) { // special marker tag; //see JSONDictionaryExtnExample.toJSON(). var e = new JSONDictionaryExtnExample(); var contents = v["class JSONDictionaryExtnExample"]; for (var i in contents) { // Reviving JSONGenericDictExample objects from string // identifiers is also special; // see JSONGenericDictExample constructor and // JSONGenericDictExample's revive() method. e[JSONGenericDictExample.revive(i)] = contents[i]; } return e; } else { return v; } }); trace("// == Here is an extended Dictionary that has been round-tripped =="); trace("// == Note that we have revived Jen/Jan during the roundtrip. =="); trace("e: " + e); //[JSONDictionaryExtnExample ] trace("e_roundtrip: " + e_roundtrip); //[JSONDictionaryExtnExample ] trace("Is e_roundtrip a JSONDictionaryExtnExample? " + (e_roundtrip is JSONDictionaryExtnExample)); //true trace("Name change: Jen is now Jan"); a_jen.dname = "Jan" trace("e: " + e); //[JSONDictionaryExtnExample ] trace("e_roundtrip: " + e_roundtrip); //[JSONDictionaryExtnExample ] 129 Dernière mise à jour le 27/4/2013 Chapitre 8 : Gestion des événements Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Un système de gestion des événements permet au programmeur de répondre aux actions de l’utilisateur et aux événements système de manière pratique. Le modèle d’événement ActionScript 3.0 n’est pas seulement pratique, il est conforme aux normes en vigueur et bien intégré à la liste d’affichage. Ce modèle repose sur la spécification d’événements Document Object Model (DOM) de niveau 3, une architecture de gestion d’événements normalisée. Il constitue donc pour les programmeurs ActionScript un outil puissant et parfaitement intuitif. Le système de gestion d’événements ActionScript 3.0 assure une interaction étroite avec la liste d’affichage. Pour comprendre les principes de base de la liste d’affichage, voir « Programmation de l’affichage » à la page 156. Voir aussi Package flash.events Spécification d’événements Document Object Model (DOM) niveau 3 Principes de base de la gestion des événements Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous pouvez concevoir un événement comme tout type d’action qui se produit dans votre fichier SWF et qui présente un intérêt pour vous en tant que programmeur. Par exemple, la plupart des fichiers SWF prennent en charge une certaine forme d’interaction, qu’il s’agisse d’une action aussi simple qu’un clic avec la souris ou d’une opération plus complexe, telle que l’acceptation et le traitement des données saisies dans un formulaire. Toute interaction de ce type dans le fichier SWF est considérée comme un événement. Des événements peuvent également se produire sans aucun interaction directe de l’utilisateur, par exemple lorsque le chargement des données depuis un serveur se termine ou qu’une caméra reliée devient active. Dans ActionScript 3.0, tout événement est représenté par un objet événement, qui correspond à une occurrence de la classe Event ou de l’une de ses sous-classes. Le rôle d’un objet événement est non seulement de stocker des informations relatives à un événement spécifique, mais aussi de contenir des méthodes qui favorisent la manipulation de cet objet. Par exemple, lorsque Flash Player ou AIR détecte un clic de la souris, il crée un objet événement (une occurrence de la classe MouseEvent) qui représente cet événement particulier. Après la création d’un objet événement, Flash Player ou AIR le distribue, ce qui signifie que l’objet événement est transmis à l’objet représentant la cible de l’événement. L’objet qui doit recevoir l’objet événement ainsi distribué est appelé cible d’événement. Par exemple, lorsqu’une caméra reliée devient active, Flash Player distribue un objet événement directement à la cible de l’événement, dans ce cas l’objet représentant la caméra. Toutefois, si la cible d’événement se trouve dans la liste d’affichage, l’objet événement est transmis tout au long de la hiérarchie de la liste d’affichage jusqu’à ce qu’il atteigne la cible en question. Dans certains cas, l’objet événement se « propage » ensuite vers le haut de la hiérarchie de la liste d’affichage, selon le même cheminement. Cette traversée de la hiérarchie de la liste d’affichage correspond au flux d’événements. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 130 Gestion des événements Dernière mise à jour le 27/4/2013 Vous pouvez « écouter » les objets événement de votre code grâce aux écouteurs d’événement. Les écouteurs d’événement sont des fonctions ou des méthodes que vous écrivez pour répondre aux différents événements. Pour garantir que le programme réagisse aux événements, vous devez ajouter des écouteurs d’événement soit à la cible d’événement, soit à l’un des objets de la liste d’affichage qui font partie du flux d’événements de l’objet événement. Chaque fois que vous écrivez un code d’écouteur d’événement, il suit cette structure de base (les éléments en gras sont des espaces réservés que vous rempliriez pour votre cas particulier) : function eventResponse(eventObject:EventType):void { // Actions performed in response to the event go here. } eventTarget.addEventListener(EventType.EVENT_NAME, eventResponse); Ce code a un double rôle. Tout d’abord, il définit une fonction, qui est une manière de spécifier les actions à exécuter en réponse à l’événement. Ensuite, il appelle la méthode addEventListener() de l’objet source, « inscrivant » ainsi la fonction auprès de l’événement spécifié de sorte que lorsque l’événement survient, les actions de la fonction ont lieu. Lorsque l’événement se produit, la cible de l’événement vérifie sa liste de toutes les fonctions et méthodes enregistrées en tant qu’écouteurs d’événement. Elle appelle ensuite chacune d’elles, transmettant l’objet événement à titre de paramètre. Vous devez apporter quatre modifications à ce code pour créer votre propre écouteur d’événement. Premièrement, vous devez remplacer le nom de la fonction par celui que vous souhaitez utiliser (ceci doit être modifié à deux endroits, là où le code indique eventResponse). Deuxièmement, vous devez spécifier le nom de la classe de l’objet événement qui est envoyé par l’événement que vous souhaitez écouter (EventType dans le code), et vous devez indiquer la constante pour l’événement en question (EVENT_NAME dans la liste). Troisièmement, vous devez appeler la méthode addEventListener() sur l’objet qui enverra l’événement (eventTarget dans ce code). Vous pouvez également modifier le nom de la variable utilisée comme paramètre de la fonction (eventObject dans ce code). Concepts importants et terminologie La liste de référence suivante contient des termes importants utilisés dans le cadre de la rédaction de routines de gestion des événements : Propagation Certains événements donnent lieu à une propagation afin de permettre à un objet d’affichage parent de réagir aux événements distribués par ses enfants. Phase de propagation Partie du flux d’événements dans laquelle un événement est propagé jusqu’aux objets d’affichage parent. La phase de propagation suit la phase de capture et la phase cible. Phase de capture Partie du flux d’événements dans laquelle un événement se propage de la cible la plus générale vers l’objet cible le plus spécifique. La phase de capture précède la phase cible et la phase de propagation. Comportement par défaut Certains événements sont liés à un comportement appelé comportement par défaut. Par exemple, lorsqu’un utilisateur tape du texte dans un champ, un événement de saisie de texte est déclenché. Le comportement par défaut de cet événement consiste à afficher le caractère tapé dans le champ de texte—mais vous pouvez annuler ce comportement par défaut (si vous ne souhaitez pas afficher le caractère tapé, par exemple). Distribuer Indiquer à des écouteurs d’événements qu’un événement a eu lieu. Evénement Opération subie par un objet et que ce dernier peut signaler à d’autres objets. Flux d’événements Lorsque des événements concernent un objet de la liste d’affichage (un objet affiché à l’écran), tous les objets qui contiennent cet objet sont informés de l’événement et avertissent à leur tour les écouteurs d’événements correspondants. Ce processus commence avec la scène et se poursuit à travers la liste d’affichage jusqu’à l’objet réel où s’est produit l’événement. Il recommence ensuite avec la scène. Ce processus est appelé flux d’événements. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 131 Gestion des événements Dernière mise à jour le 27/4/2013 Objet événement Objet contenant des informations sur l’occurrence d’un événement particulier, qui est envoyé à tous les écouteurs lorsqu’un événement est distribué. Cible d’événement Objet qui envoie un événement. Par exemple, si l’utilisateur clique sur un bouton situé dans un Sprite se trouvant dans la scène, tous ces objets envoient des événements mais c’est au niveau de la cible d’événement que se produit l’événement (le bouton cliqué, dans ce cas). Ecouteur Objet ou fonction qui s’est enregistré auprès d’un objet pour indiquer qu’il doit être averti lorsqu’un événement spécifique se produit. Phase cible Stade du flux d’événements où un événement atteint la cible la plus spécifique possible. La phase cible se produit entre la phase de capture et la phase de propagation. Variation de la gestion d’événements dans ActionScript 3.0 par rapport aux versions antérieures Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures En ce qui concerne la gestion des événements, la différence la plus évidente entre ActionScript 3.0 et les versions antérieures est qu’ActionScript 3.0 comprend un seul système de gestion des événements alors que les anciennes versions d’ActionScript en comptent plusieurs. Cette section commence par une présentation générale du fonctionnement de la gestion des événements dans les versions précédentes, puis étudie les nouveautés qu’apporte ActionScript 3.0 dans ce domaine. Gestion des événements dans les versions précédentes d’ActionScript Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Antérieurement à ActionScript 3.0, le langage ActionScript fournissait plusieurs méthodes de gestion des événements : • Les gestionnaires d’événement on(), qui peuvent se placer directement sur des occurrences Button et MovieClip • Les gestionnaires d’événement onClipEvent(), qui peuvent se placer directement sur des occurrences MovieClip • Des propriétés de fonction de rappel, telles que XML.onload et Camera.onActivity • Des écouteurs d’événement, que vous pouvez enregistrer à l’aide de la méthode addListener() • La classe UIEventDispatcher, qui implémentait partiellement le modèle d’événements DOM Chacun de ces mécanismes présente des avantages et des inconvénients. Les gestionnaires on() et onClipEvent() sont simples d’utilisation, mais compliquent la maintenance des projets car il peut s’avérer difficile de localiser le code placé directement sur les boutons ou les clips. Les fonctions de rappel sont également faciles à implémenter, mais imposent une limite d’une seule fonction de rappel par événement. L’implémentation des écouteurs d’événement est plus complexe : ils nécessitent non seulement la création d’un objet et d’une fonction d’écouteur, mais aussi l’enregistrement de l’écouteur auprès de l’objet qui génère l’événement. Bien qu’elle accroisse le temps système nécessaire, cette solution vous permet de créer plusieurs objets écouteur et de tous les enregistrer pour le même événement. Dans ActionScript 2.0, le développement des composants engendrait un modèle d’événements encore différent. Ce nouveau modèle, caractérisé par la classe UIEventDispatcher, reposait sur un sous-ensemble de la spécification d’événements DOM. Ainsi, pour les développeurs accoutumés à la gestion des événements de composant, le passage au nouveau modèle d’événements d’ActionScript 3.0 se fera sans trop de difficultés. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 132 Gestion des événements Dernière mise à jour le 27/4/2013 Malheureusement, si l’on constate des recoupements entre les divers modèles d’événements, il existe aussi des différences. Par exemple, dans ActionScript 2.0, certaines propriétés, telles que TextField.onChanged, peuvent s’utiliser soit comme fonction de rappel, soit comme écouteur d’événement. Toutefois, la syntaxe qui permet d’enregistrer les objets écouteurs varie selon que vous utilisez l’une des six classes qui prennent en charge les écouteurs ou la classe UIEventDispatcher. Pour les classes Key, Mouse, MovieClipLoader, Selection, Stage et TextField, vous utilisez la méthode addListener(), mais pour la gestion des événements de composant, vous utilisez une méthode appelée addEventListener(). La multiplicité des modèles de gestion d’événements a fait naître une autre complexité : l’étendue de la fonction de gestionnaire d’événement variait largement en fonction du mécanisme utilisé. En d’autres termes, la signification du mot-clé this n’était pas cohérente sur l’ensemble des systèmes de gestion d’événements. Gestion d’événements dans ActionScript 3.0 Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures ActionScript 3.0 utilise pour la première fois un modèle de gestion d’événements qui vient remplacer les nombreux mécanismes qui existaient dans les précédentes versions du langage. Le nouveau modèle d’événements repose sur la spécification d’événements de niveau 3 DOM (Document Object Model). Bien que le format de fichier SWF ne suive pas spécifiquement la norme DOM, il existe suffisamment de similitudes entre la liste d’affichage et la structure du DOM pour permettre l’implémentation de ce modèle d’événements. Un objet de la liste d’affichage est semblable à un noeud de la structure hiérarchique du DOM ; dans ce chapitre, les termes objet de liste d’affichage et noeud sont d’ailleurs utilisés de façon interchangeable. L’implémentation du modèle d’événements DOM dans Flash Player et AIR comprend un concept appelé « comportements par défaut ». Un comportement par défaut est une action que Flash Player ou AIR effectue comme conséquence normale de certains événements. Comportements par défaut Les développeurs se chargent normalement d’écrire le code qui permet de répondre aux événements. Dans certains cas, cependant, un comportement est si couramment associé à un événement que Flash Player ou AIR l’exécute automatiquement, sauf si le développeur ajoute du code pour annuler son exécution. Comme Flash Player ou AIR se livre automatiquement à cette opération, on parle de comportements par défaut. Par exemple, lorsqu’un utilisateur entre du texte dans un objet TextField, il est si courant de voir s’afficher la saisie dans l’objet TextField en question que ce comportement est prédéfini dans Flash Player ou AIR. Si vous ne souhaitez pas conserver ce comportement par défaut, vous pouvez l’annuler à l’aide du système de gestion des événements. Lorsqu’un utilisateur entre du texte dans un objet TextField, Flash Player ou AIR crée une occurrence de la classe TextEvent afin de représenter cette saisie. Pour éviter que Flash Player ou AIR n’affiche le texte dans l’objet TextField, vous devez accéder à cette occurrence de TextEvent spécifique et appeler sa méthode preventDefault(). Certains comportements par défaut ne peuvent pas être évités. Par exemple, Flash Player et AIR génèrent un objet MouseEvent lorsque l’utilisateur double-clique sur un mot dans un objet TextField. Le comportement par défaut, qui ne peut être évité, consiste à mettre en évidence le mot situé sous le curseur. De nombreux types d’objets événement ne sont associés à aucun comportement par défaut. Par exemple, l’objet événement Connect, que Flash Player distribue lorsqu’une connexion réseau est établie, n’est associé à aucun comportement par défaut. La documentation de l’API relative à la classe Event et ses sous-classes fait l’inventaire de chaque type d’événement, décrit le comportement par défaut qui lui est éventuellement associé et indique si ce dernier peut être évité. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 133 Gestion des événements Dernière mise à jour le 27/4/2013 Il est important de comprendre que les comportements par défaut sont uniquement associés à des objets événements distribués par Flash Player ou AIR ; il n’en existe aucun pour les objets événements distribués via ActionScript par programmation. Par exemple, vous pouvez utiliser les méthodes de la classe EventDispatcher pour distribuer un objet événement du type textInput, mais cet objet ne sera associé à aucun comportement par défaut. En d’autres termes, Flash Player et AIR n’affichent aucun caractère dans un objet TextField en réponse à un événement textInput que vous avez distribué par programmation. Nouveautés des écouteurs d’événement dans ActionScript 3.0 Pour les développeurs qui connaissent bien la méthode ActionScript 2.0 addListener(), il peut être utile de souligner les différences entre le modèle d’écouteur d’événement d’ActionScript 2.0 et le modèle d’événements d’ActionScript 3.0. La liste ci-après décrit les principales différences entre ces deux modèles d’événements : • Pour ajouter des écouteurs d’événement dans ActionScript 2.0, vous utilisez, selon le cas, addListener() ou addEventListener(). Dans ActionScript 3.0, il faut utiliser addEventListener() dans tous les cas. • ActionScript 2.0 ne propose aucun flux d’événements dans ActionScript 2.0, ce qui signifie que la méthode addListener() peut uniquement être appelée sur l’objet qui émet l’événement. Dans ActionScript 3.0, la méthode addEventListener() peut être appelée sur tout objet faisant partie du flux d’événements. • Dans ActionScript 2.0, les écouteurs d’événement peuvent être des fonctions, des méthodes ou des objets, alors que dans ActionScript 3.0, seules les fonctions et les méthodes peuvent agir comme écouteurs d’événement. Flux d’événements Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Flash Player ou AIR distribue des objets événements dès que survient un événement. Si la cible d’événement ne se trouve pas dans la liste d’affichage, Flash Player ou AIR distribue l’objet événement directement à la cible. Par exemple, Flash Player distribue l’objet événement Progress directement à un objet URLStream. Cependant, si la cible d’événement se trouve dans la liste d’affichage, Flash Player distribue l’objet événement à la liste d’affichage, dans laquelle l’objet chemine jusqu’à atteindre la cible d’événement. Le flux d’événements représente le parcours que suivra un objet événement dans la liste d’affichage. Cette liste s’organise de manière hiérarchique, pour constituer une arborescence. Au sommet de la liste d’affichage se trouve la scène, un conteneur d’objet d’affichage spécial qui lui sert de racine. La Scène, représentée par la classe flash.display.Stage, est uniquement accessible via un objet d’affichage. Chaque objet d’affichage présente une propriété appelée stage, qui renvoie à la scène de cette application. Lorsque Flash Player ou AIR distribue un objet d’événement pour un événement associé à une liste d’affichage, celuici effectue un aller-retour entre la Scène et le noeud cible. Selon la définition de la spécification d’événements DOM, le noeud cible est le noeud qui représente la cible d’événement. En d’autres termes, le noeud cible est l’objet de la liste d’affichage au niveau duquel est survenu l’événement. Par exemple, si l’utilisateur clique sur un objet de la liste d’affichage appelé child1, Flash Player ou AIR distribue un objet événement dont le noeud cible est child1. Le flux d’événements se décompose en trois phases. La première correspond à la phase de capture, qui comprend tous les noeuds de la Scène jusqu’au parent du noeud cible. La deuxième partie est appelée la phase cible, qui comprend uniquement le noeud cible. La troisième partie s’appelle la phase de propagation. Elle comprend les noeuds rencontrés lors du cheminement du parent du noeud cible jusqu’à la scène. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 134 Gestion des événements Dernière mise à jour le 27/4/2013 Le nom de ces phases prend tout son sens si vous envisagez la liste d’affichage comme une hiérarchie verticale dont le sommet est la Scène, comme illustré par le schéma suivant : Si un utilisateur clique sur Child1 Node, Flash Player ou AIR distribue un objet événement dans ce flux d’événements. Comme le montre l’illustration suivante, le parcours de l’objet commence à Scène. L’objet descend ensuite jusqu’à Noeud parent, puis vers Noeud enfant1. Il se propage alors vers le haut jusqu’à Scène, en repassant par Noeud parent pour rejoindre Scène. Dans cet exemple, la phase de capture comprend Scène et Noeud parent pendant le trajet descendant initial. La phase cible comprend le temps passé au noeud Noeud enfant1. La phase de propagation comprend les noeuds Noeud parent et Scène, qui se trouvent sur le chemin du retour vers le noeud racine. Le flux d’événements contribue au renforcement du système de gestion des événements par rapport aux versions précédentes d’ActionScript. Dans ces dernières, le flux d’événements est inexistant, ce qui signifie que les écouteurs d’événement s’ajoutent uniquement à l’objet qui génère l’événement. Dans ActionScript 3.0, vous pouvez ajouter des écouteurs d’événement aussi bien à un noeud cible qu’à tout autre noeud du flux d’événements. Cette possibilité d’ajouter des écouteurs d’événement tout au long du flux d’événements s’avère particulièrement utile lorsqu’un composant d’interface comprend plusieurs objets. Par exemple, un objet bouton contient souvent un objet texte qui sert de libellé au bouton. Sans la possibilité d’ajouter un écouteur au flux d’événements, il faudrait en ajouter un à l’objet bouton et un à l’objet texte pour être sûr d’être averti des événements de clic survenant à tout endroit du bouton. Le flux d’événements vous permet, au contraire, de placer un seul écouteur d’événement sur l’objet bouton afin de gérer les événements de clic, qu’ils se produisent sur l’objet texte ou sur des zones de l’objet bouton non couvertes par l’objet texte. Cependant, certains objets événements ne participent pas aux trois phases du flux d’événements. Certains types d’événements, tels que enterFrame et init, sont distribués directement au noeud cible et ne participent ni à la phase de capture, ni à la phase de propagation. D’autres événements peuvent cibler des objets qui ne font pas partie de la liste d’affichage, par exemple les événements distribués à une occurrence de la classe Socket. Ces objets événements aboutissent directement à l’objet cible, sans participer à la phase de capture et de propagation. Scène Noeud parent Noeud enfant1 Noeud enfant2 GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 135 Gestion des événements Dernière mise à jour le 27/4/2013 Pour savoir comment se comporte un type d’événement particulier, vous pouvez consulter la documentation de l’API ou examiner les propriétés de l’objet événement. Cette dernière méthode est décrite à la section suivante. Objets événement Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les objets événements jouent deux rôles essentiels dans le nouveau système de gestion des événements. Tout d’abord, ces objets représentent de véritables événements, puisqu’ils stockent dans un ensemble de propriétés des informations relatives à des événements précis. Ils contiennent en outre un jeu de méthodes qui vous permet de manipuler les objets événement et d’agir sur le comportement du système de gestion des événements. Pour faciliter l’accès à ces propriétés et ces méthodes, l’API Flash Player définit une classe Event qui constitue la classe de base de tous les objets événements. La classe Event définit un jeu fondamental de propriétés et de méthodes commun à tous les objets événement. Cette section commence par étudier les propriétés de la classe Event avant de décrire les méthodes de cette même classe, puis explique l’existence de sous-classes dans la classe Event. Présentation des propriétés de la classe Event Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe Event définit plusieurs propriétés et constantes en lecture seule qui fournissent des informations essentielles sur l’objet événement. Les points suivants revêtent une importance particulière : • Les types d’objet événement sont représentés par des constantes et stockés dans la propriété Event.type. • La possibilité d’éviter le comportement par défaut d’un événement est représentée par une valeur booléenne, stockée dans la propriété Event.cancelable. • Les informations relatives au flux d’événements se trouvent dans les propriétés restantes. Types d’objets événement Chaque objet événement est associé à un type d’événement. Les types d’événements sont stockés dans la propriété Event.type sous forme de chaîne. Il est utile de connaître le type d’un objet événement car votre code peut alors distinguer les objets de types différents. Par exemple, le code suivant spécifie que la fonction clickHandler() doit répondre à tous les objets événements clic de souris transmis à myDisplayObject : myDisplayObject.addEventListener(MouseEvent.CLICK, clickHandler); La classe Event est elle-même associée à deux douzaines de types d’événement, représentés par des constantes de la classe Event. Dans cet extrait de la définition de la classe Event, certaines de ces constantes sont illustrées : package flash.events { public class Event { // class constants public static const ACTIVATE:String = "activate"; public static const ADDED:String= "added"; // remaining constants omitted for brevity } } GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 136 Gestion des événements Dernière mise à jour le 27/4/2013 Ces constantes permettent de faire facilement référence à des types d’événement précis. Vous devez utiliser ces constantes au lieu des chaînes qu’elles représentent. Si vous orthographiez de manière incorrecte un nom de constante dans votre code, le compilateur peut détecter l’erreur. Si vous utilisez les chaînes qu’elles représentent, une erreur de frappe ne sera pas forcément détectée lors de la compilation et pourrait provoquer un comportement inattendu, difficile à déboguer. Par exemple, utilisez le code suivant pour ajouter un écouteur d’événement : myDisplayObject.addEventListener(MouseEvent.CLICK, clickHandler); plutôt que : myDisplayObject.addEventListener("click", clickHandler); Informations relatives aux comportements par défaut Le code que vous écrivez est en mesure de vérifier si le comportement par défaut d’un objet événement donné peut être évité. Pour ce faire, il doit accéder à la propriété cancelable. La propriété cancelable contient une valeur booléenne qui indique si le comportement par défaut peut être évité ou non. Vous pouvez éviter, ou annuler, le comportement par défaut de quelques événements à l’aide de la méthode preventDefault(). Pour plus d’informations, voir Annulation d’un comportement associé par défaut à un événement sous « Présentation des méthodes de la classe Event » à la page 137. Informations de flux d’événements Les propriétés restantes de la classe Event contiennent des informations importantes sur l’objet événement et ses relations au flux d’événements, comme l’explique la liste suivante : • La propriété bubbles contient des informations sur les parties du flux d’événements auquel participe l’objet événement. • La propriété eventPhase indique la phase actuelle du flux d’événements. • La propriété target stocke une référence à la cible d’événement. • La propriété currentTarget stocke une référence de l’objet de liste d’affichage qui traite actuellement l’objet événement. La propriété bubbles On dit d’un événement qu’il se propage lorsqu’il participe à la phase de propagation du flux d’événements, c’est-à-dire quand l’objet événement est transmis du noeud cible via ses ascendants jusqu’à la Scène. La propriété Event.bubbles stocke une valeur booléenne qui indique si l’objet événement participe à la phase de propagation. Tous les événements qui se propagent vers le haut participent également aux phases de capture et cible ; de tels événements participent donc aux trois phases du flux d’événements. Si la valeur est true, l’objet événement participe aux trois phrases. Si la valeur est false, l’objet événement ne participe pas à la phase de propagation. La propriété eventPhase Vous pouvez déterminer la phase d’événement de tout objet événement grâce à sa propriété eventPhase. La propriété eventPhase a pour valeur un entier non signé qui représente l’une des trois phases du flux d’événements. L’API de Flash Player définit une classe EventPhase distincte qui contient trois constantes correspondant aux trois valeurs entières non signées, comme illustré par l’extrait de code suivant : GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 137 Gestion des événements Dernière mise à jour le 27/4/2013 package flash.events { public final class EventPhase { public static const CAPTURING_PHASE:uint = 1; public static const AT_TARGET:uint = 2; public static const BUBBLING_PHASE:uint= 3; } } Ces constantes correspondent aux trois valeurs valables pour la propriété eventPhase. Vous pouvez utiliser ces constantes pour améliorer la lisibilité de votre code. Supposons par exemple que vous souhaitiez être sûr qu’une fonction appelée myFunc() soit uniquement appelée lorsque la cible d’événement se trouve dans la scène cible. Le code suivant vous permet de tester cette condition : if (event.eventPhase == EventPhase.AT_TARGET) { myFunc(); } La propriété target La propriété target contient une référence à l’objet cible de l’événement. Dans certains cas, ce système est simple, par exemple, lorsqu’un micro devient actif, la cible de l’objet événement est l’objet Microphone. Toutefois, si la cible se trouve sur la liste d’affichage, il faut tenir compte de la hiérarchie de cette dernière. Par exemple, si un utilisateur clique avec la souris sur un point correspondant à plusieurs objets de la liste d’affichage qui se chevauchent, Flash Player et AIR choisissent toujours comme cible d’événement l’objet qui se trouve le plus loin de la Scène. Dans des fichiers SWF complexes, et particulièrement ceux dont les boutons sont régulièrement ornés d’objets enfant plus petits, la propriété target ne doit pas être utilisée fréquemment car elle pointera souvent vers l’objet enfant du bouton plutôt que vers le bouton lui-même. Dans de telles situations, il est courant d’ajouter des écouteurs d’événement au bouton et d’utiliser la propriété currentTarget. En effet, cette dernière pointe vers le bouton alors que la propriété target peut pointer vers l’un des enfants du bouton. La propriété currentTarget La propriété currentTarget contient une référence de l’objet de liste d’affichage qui traite actuellement l’objet événement. Même s’il peut paraître étrange de ne pas savoir quel noeud traite actuellement l’objet événement que vous étudiez, gardez à l’esprit que vous pouvez ajouter une fonction écouteur à n’importe quel objet d’affichage du flux d’événements de l’objet événement en question. En outre, cette fonction écouteur peut être placée à tout endroit. Par ailleurs, la même fonction écouteur peut être ajoutée à différents objets d’affichage. L’utilité de la propriété currentTarget augmente donc avec la taille et la complexité du projet. Présentation des méthodes de la classe Event Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe Event contient trois catégories de méthodes : • Les méthodes d’utilitaire, qui peuvent créer des copies d’un objet événement ou le convertir en chaîne • Les méthodes de flux d’événements, qui suppriment les objets événements du flux d’événements • Les méthodes de comportement par défaut, qui annulent le comportement par défaut ou vérifient s’il a été annulé GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 138 Gestion des événements Dernière mise à jour le 27/4/2013 Méthodes d’utilitaire de la classe Event La classe Event compte deux méthodes d’utilitaire. La méthode clone() permet de créer des copies d’un objet événement. La méthode toString() permet de représenter sous forme de chaînes les propriétés d’un objet événement ainsi que leurs valeurs. Bien qu’utilisées en interne par le modèle d’événements, ces deux méthodes sont mises à la disposition des développeurs pour un usage générique. Pour les développeurs expérimentés qui souhaitent créer des sous-classes de la classe Event, il est nécessaire de redéfinir et d’implémenter des versions de ces deux méthodes d’utilitaires afin de garantir le bon fonctionnement de la sous-classe d’événement. Arrêt du flux d’événements La méthode Event.stopPropagation() ou Event.stopImmediatePropagation() vous permet d’arrêter le cheminement d’un objet événement dans le flux d’événements. Quasi identiques, ces deux méthodes diffèrent uniquement en ce que les autres écouteurs d’événement du noeud actuel sont autorisés ou non à s’exécuter : • La méthode Event.stopPropagation() empêche l’objet événement de passer au noeud suivant mais seulement après que tous les autres écouteurs du noeud actuel ont été autorisés à s’exécuter. • La méthode Event.stopImmediatePropagation() empêche l’objet événement de passer au noeud suivant sans autoriser les autres écouteurs du noeud actuel à s’exécuter. Quelle que soit la méthode appelée, elle n’a aucun effet sur la réalisation du comportement par défaut de l’événement. Utilisez les méthodes de comportement par défaut de la classe Event pour éviter le comportement par défaut. Annulation d’un comportement associé par défaut à un événement Deux méthodes sont associées à l’annulation du comportement par défaut : preventDefault() et isDefaultPrevented(). Appelez la méthode preventDefault() pour annuler le comportement associé par défaut à un événement. Pour vérifier si preventDefault() a déjà été appelée sur un objet événement, appelez la méthode isDefaultPrevented(), qui renvoie la valeur true si la méthode a déjà été appelée, false dans le cas contraire. La méthode preventDefault() fonctionne uniquement s’il est possible d’annuler le comportement par défaut de l’événement. Pour vérifier que c’est le cas, reportez-vous à la documentation de l’API de ce type d’événement ou examinez la propriété cancelable de l’objet événement à l’aide du code ActionScript. L’annulation du comportement par défaut n’a aucun effet sur la progression d’un objet événement dans le flux d’événements. Utilisez les méthodes de flux d’événements de la classe Event pour supprimer un objet événement du flux d’événements. Sous-classes de la classe Event Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour de nombreux événements, le jeu de propriétés commun, défini dans la classe Event est suffisant. Néanmoins, d’autres événements présentent des caractéristiques exclusives qui ne peuvent être capturées par les propriétés disponibles dans la classe Event. Pour ces événements, ActionScript 3.0 définit plusieurs sous-classes de la classe Evénement. Chaque sous-classe fournit d’autres propriétés et types d’événements propres à la catégorie d’événement considérée. Par exemple, les événements liés aux actions de la souris présentent plusieurs caractéristiques uniques, que les propriétés définies dans la classe Event ne peuvent capturer. La classe MouseEvent constitue une extension de la classe Event puisqu’elle ajoute dix propriétés contenant des informations telles que l’emplacement de l’événement de souris et les éventuelles touches actionnées en même temps. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 139 Gestion des événements Dernière mise à jour le 27/4/2013 Une sous-classe d’Event contient également des constantes qui représentent de types d’événement associés à la sousclasse. Par exemple, la classe MouseEvent définit des constantes pour plusieurs types d’événement de souris, notamment click, doubleClick, mouseDown et mouseUp. Comme le décrit la section consacrée aux méthodes d’utilitaire de la classe Event dans « Objets événement » à la page 135, lors de la création d’une sous-classe d’Event, vous devez bloquer les méthodes clone() et toString() pour fournir la fonctionnalité propre à la sous-classe. Ecouteurs d’événement Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les écouteurs d’événement, également appelés gestionnaires d’événements, sont des fonctions que Flash Player et AIR exécutent en réponse à des événements déterminés. La procédure d’ajout d’un écouteur d’événement se déroule en deux temps. En premier lieu, vous créez une fonction ou méthode de classe que Flash Player ou AIR doit exécuter en réponse à l’événement. On parle parfois de fonction d’écouteur ou de fonction de gestionnaire d’événement. En second lieu, vous utilisez la méthode addEventListener() pour enregistrer la fonction d’écouteur auprès de la cible de l’événement ou tout autre objet de la liste d’affichage qui appartient au flux d’événements approprié. Création d’une fonction d’écouteur Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La création d’une fonction d’écouteur est un domaine dans lequel le modèle d’événements ActionScript 3.0 diffère du modèle d’événements DOM. Dans le modèle d’événements DOM, on distingue clairement un écouteur d’événement et une fonction d’écouteur : un écouteur d’événement est une occurrence de classe qui implémente l’interface EventListener, tandis qu’une fonction d’écouteur est une méthode de cette classe appelée handleEvent(). Dans le modèle d’événements DOM, vous enregistrez l’occurrence de classe qui contient la fonction d’écouteur, plutôt que la fonction d’écouteur elle-même. Le modèle d’événements ActionScript ne fait aucune distinction entre l’écouteur d’événement et la fonction d’écouteur. L’interface EventListener est inexistante dans ActionScript 3.0 et les fonctions d’écouteur peuvent être définies en dehors de toute classe ou au sein d’une classe. Par ailleurs, il n’est pas nécessaire de nommer les fonctions d’écouteur handleEvent() ; vous pouvez utiliser tout identifiant valable. Dans ActionScript 3.0, vous enregistrez le nom de la fonction d’écouteur elle-même. Fonction d’écouteur définie en dehors de toute classe Le code suivant crée un fichier SWF simple qui affiche une forme carrée de couleur rouge. Une fonction d’écouteur appelée clickHandler(), qui n’appartient à aucune classe, écoute les événements de clic de souris dans le carré rouge. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 140 Gestion des événements Dernière mise à jour le 27/4/2013 package { import flash.display.Sprite; public class ClickExample extends Sprite { public function ClickExample() { var child:ChildSprite = new ChildSprite(); addChild(child); } } } import flash.display.Sprite; import flash.events.MouseEvent; class ChildSprite extends Sprite { public function ChildSprite() { graphics.beginFill(0xFF0000); graphics.drawRect(0,0,100,100); graphics.endFill(); addEventListener(MouseEvent.CLICK, clickHandler); } } function clickHandler(event:MouseEvent):void { trace("clickHandler detected an event of type: " + event.type); trace("the this keyword refers to: " + this); } Lorsqu’un utilisateur interagit avec le fichier SWF résultant, en cliquant sur le carré, Flash Player ou AIR génère la sortie de suivi ci-après : clickHandler detected an event of type: click the this keyword refers to: [object global] Notez que l’objet événement est transmis sous forme d’instruction à clickHandler(). Cela permet à votre fonction d’écouteur d’examiner l’objet événement. Dans cet exemple, vous utilisez la propriété type de l’objet événement pour vérifier que cet événement correspond à un clic. L’exemple vérifie aussi la valeur du mot-clé this. Dans ce cas, this représente l’objet global, ce qui est logique puisque la fonction est définie en dehors de toute classe ou objet personnalisé. Fonction d’écouteur définie comme méthode de classe L’exemple ci-dessous est identique au précédent, qui définit la classe ClickExample, sauf que la fonction clickHandler() est définie comme méthode de la classe ChildSprite : GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 141 Gestion des événements Dernière mise à jour le 27/4/2013 package { import flash.display.Sprite; public class ClickExample extends Sprite { public function ClickExample() { var child:ChildSprite = new ChildSprite(); addChild(child); } } } import flash.display.Sprite; import flash.events.MouseEvent; class ChildSprite extends Sprite { public function ChildSprite() { graphics.beginFill(0xFF0000); graphics.drawRect(0,0,100,100); graphics.endFill(); addEventListener(MouseEvent.CLICK, clickHandler); } private function clickHandler(event:MouseEvent):void { trace("clickHandler detected an event of type: " + event.type); trace("the this keyword refers to: " + this); } } Lorsqu’un utilisateur interagit avec le fichier SWF résultant, en cliquant sur le carré rouge, Flash Player ou AIR génère la sortie de suivi ci-après : clickHandler detected an event of type: click the this keyword refers to: [object ChildSprite] Notez que le mot-clé this renvoie à l’occurrence de ChildSprite appelée child. Voici un changement de comportement par rapport à ActionScript 2.0. Si vous utilisiez des composants dans ActionScript 2.0, vous vous rappelez sans doute que lorsqu’une méthode de classe était transmise à UIEventDispatcher.addEventListener(), l’étendue de la méthode était liée au composant qui émettait l’événement, et non à la classe dans laquelle la méthode d’écouteur était définie. En d’autres termes, si vous utilisiez cette technique dans ActionScript 2.0, le mot-clé this renvoyait au composant émettant l’événement et non à l’occurrence de ChildSprite. Pour certains développeurs, il s’agissait d’un vrai problème car cela signifiait qu’ils ne pouvaient accéder à aucune autre méthode et propriété de la classe qui contenait la méthode d’écouteur. Pour le contourner, les programmeurs d’ActionScript 2.0 pouvaient utiliser la classe mx.util.Delegate pour modifier l’étendue de la méthode d’écouteur. Cette manipulation n’est plus nécessaire puisque ActionScript 3.0 crée une méthode liée lorsque addEventListener() est appelée. Par conséquent, le mot-clé this fait référence à l’occurrence de ChildSprite appelée child et le programmeur peut accéder aux autres méthodes et propriétés de la classe ChildSprite. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 142 Gestion des événements Dernière mise à jour le 27/4/2013 Ecouteur d’événement à ne pas utiliser Une troisième technique permet de créer un objet générique dont l’une des propriétés pointe vers une fonction d’écouteur affectée dynamiquement. Elle est cependant déconseillée. Nous l’évoquons ici en raison de son utilisation courante dans ActionScript 2.0 ; il n’est toutefois pas recommandé de l’utiliser dans ActionScript 3.0. Cette mise en garde tient au fait que le mot-clé this fera référence à l’objet global et non à l’objet écouteur. L’exemple ci-après est identique à l’exemple précédent de la classe ClickExample, sauf que la fonction d’écouteur est définie comme faisant partie d’un objet générique appelé myListenerObj : package { import flash.display.Sprite; public class ClickExample extends Sprite { public function ClickExample() { var child:ChildSprite = new ChildSprite(); addChild(child); } } } import flash.display.Sprite; import flash.events.MouseEvent; class ChildSprite extends Sprite { public function ChildSprite() { graphics.beginFill(0xFF0000); graphics.drawRect(0,0,100,100); graphics.endFill(); addEventListener(MouseEvent.CLICK, myListenerObj.clickHandler); } } var myListenerObj:Object = new Object(); myListenerObj.clickHandler = function (event:MouseEvent):void { trace("clickHandler detected an event of type: " + event.type); trace("the this keyword refers to: " + this); } Les résultats de trace seront les suivants : clickHandler detected an event of type: click the this keyword refers to: [object global] On s’attendrait à ce que this fasse référence à myListenerObj et que la sortie de suivi soit [object Object], mais le mot-clé renvoie en fait à l’objet global. Lorsque vous transmettez un nom de propriété dynamique comme instruction à addEventListener(), Flash Player ou AIR est incapable de créer une méthode liée. En effet, ce que vous transmettez comme paramètre listener n’est rien de plus que l’adresse mémoire de votre fonction d’écouteur ; Flash Player et AIR n’ont aucun moyen de lier cette adresse à l’occurrence de myListenerObj. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 143 Gestion des événements Dernière mise à jour le 27/4/2013 Gestion des écouteurs d’événement Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous pouvez gérer vos fonctions d’écouteur à l’aide des méthodes de l’interface IEventDispatcher. Cette interface est la version ActionScript 3.0 de l’interface EventTarget du modèle d’événements DOM. Bien que le nom IEventDispatcher semble impliquer que l’objet principal de la classe est l’envoi (ou la distribution) des objets événements, les méthodes qui lui correspondent servent en fait plus souvent à l’enregistrement, la vérification et la suppression des écouteurs d’événement. L’interface IEventDispatcher définit cinq méthodes, comme illustré dans le code suivant : package flash.events { public interface IEventDispatcher { function addEventListener(eventName:String, listener:Object, useCapture:Boolean=false, priority:Integer=0, useWeakReference:Boolean=false):Boolean; function removeEventListener(eventName:String, listener:Object, useCapture:Boolean=false):Boolean; function dispatchEvent(eventObject:Event):Boolean; function hasEventListener(eventName:String):Boolean; function willTrigger(eventName:String):Boolean; } } L’API de Flash Player implémente l’interface IEventDispatcher à l’aide de la classe Event Dispatcher. Cette dernière constitue la classe de base de toutes les classes pouvant servir de cibles d’événement ou faire partie d’un flux d’événements. Par exemple, la classe DisplayObject hérite de la classe EventDispatcher, par conséquent, tout objet de la liste d’affichage peut accéder aux méthodes de l’interface IEventDispatcher. Ajout des écouteurs d’événement La méthode addEventListener() est la clé de voûte de l’interface IEventDispatcher. Elle permet d’enregistrer les fonctions d’écouteurs. Les deux paramètres requis sont type et listener. Le paramètre type spécifie le type d’événement. Avec le paramètre listener, vous pouvez spécifier la fonction d’écouteur qui doit s’exécuter lorsque l’événement survient. Le paramètre listener peut être une référence à une fonction ou une méthode de classe. n’utilisez pas de parenthèses pour stipuler le paramètre listener. Par exemple, la fonction clickHandler() est spécifiée sans parenthèses dans l’appel suivant à la méthode addEventListener() : addEventListener(MouseEvent.CLICK, clickHandler) Le paramètre useCapture de la méthode addEventListener() vous permet de contrôler la phase du flux d’événements pendant laquelle votre écouteur sera actif. Si useCapture a la valeur true, votre écouteur sera actif pendant la phase de capture du flux d’événements. Si useCapture a la valeur false, votre écouteur sera actif pendant la phase cible et la phase de propagation du flux d’événements. Pour écouter un événement pendant toutes les phases du flux d’événements, vous devez appeler deux fois addEventListener() ; la première fois, useCapture prend la valeur true, la seconde fois, useCapture prend la valeur false. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 144 Gestion des événements Dernière mise à jour le 27/4/2013 Le paramètre priority de la méthode addEventListener() ne fait pas officiellement partie du modèle d’événements DOM de niveau 3. Il est inclus dans ActionScript 3.0 pour vous offrir une plus grande souplesse dans l’organisation de vos écouteurs d’événement. Lorsque vous appelez addEventListener(), vous pouvez définir la priorité de cet écouteur d’événement en transmettant une valeur entière comme paramètre priority. La valeur par défaut est 0. Vous pouvez toutefois utiliser une valeur entière négative ou positive. Plus le nombre est élevé, plus l’exécution de l’écouteur d’événement est rapide. Les écouteurs d’événement de priorité équivalente sont exécutés suivant l’ordre dans lequel ils ont été ajoutés : plus l’écouteur est ajouté tôt, plus il est exécuté rapidement. Le paramètre useWeakReference vous permet de spécifier si la référence à la fonction d’écouteur est faible ou normale. En lui attribuant la valeur true, vous évitez les situations dans lesquelles les fonctions d’écouteurs demeurent dans la mémoire alors qu’elles sont inutiles. Flash Player et AIR utilisent une technique appelée nettoyage pour effacer de la mémoire les objets qui ne servent plus. Un objet est considéré comme inutilisé lorsqu’il n’apparaît dans aucune référence. Le nettoyeur de mémoire ignore les références faibles, c’est-à-dire qu’une fonction d’écouteur vers laquelle pointe uniquement une référence faible est incluse dans le nettoyage. Suppression des écouteurs d’événement La méthode removeEventListener() permet de supprimer un écouteur d’événement dont vous n’avez plus besoin. Il est judicieux de supprimer tous les écouteurs qui ne seront plus utilisés. Les paramètres requis sont notamment eventName et listener, soit les mêmes que ceux requis pour la méthode addEventListener(). Rappel : pour écouter les événements pendant toutes les phases du flux d’événements, vous pouvez appeler addEventListener() deux fois, en attribuant à useCapture la valeur true la première, puis false la seconde. Pour supprimer les deux écouteurs d’événement, il serait nécessaire d’appeler removeEventListener() à deux reprises, la première fois en attribuant la valeur true à useCapture, la seconde fois en utilisant la valeur false. Distribution d’événements La méthode dispatchEvent() peut servir aux développeurs chevronnés pour distribuer un objet événement personnalisé dans le flux d’événements. Cette méthode accepte un seul paramètre, une référence à l’objet événement, qui doit être une occurrence de la classe Event ou de l’une de ces sous-classes. Après distribution, la propriété target de l’objet événement est définie avec l’objet sur lequel portait l’appel dispatchEvent(). Vérification des écouteurs d’événement existants Les deux dernières méthodes de l’interface IEventDispatcher fournissent des informations précieuses sur l’existence des écouteurs d’événement. La méthode hasEventListener() renvoie la valeur true si un écouteur d’événement est détecté pour un type d’événement spécifique sur un objet particulier de la liste d’affichage. La méthode willTrigger() renvoie également la valeur true si un écouteur est détecté pour un objet donné de la liste d’affichage. Cependant willTrigger() vérifie les écouteurs sur l’objet d’affichage en question mais également sur tous les ascendants de cet objet dans l’ensemble des phases du flux d’événements. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 145 Gestion des événements Dernière mise à jour le 27/4/2013 Evénements d’erreur sans écouteurs Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Plus que les événements, les exceptions constituent le mécanisme principal de gestion des erreurs dans ActionScript 3.0. Toutefois, la gestion des exceptions ne fonctionne pas sur les opérations asynchrones telles que les chargements de fichiers. Si une erreur survient pendant une opération asynchrone, Flash Player et AIR distribuent un objet événement d’erreur. Si vous ne créez pas d’écouteur pour l’événement d’erreur, les versions de débogage de Flash Player et AIR affichent une boîte de dialogue comportant des informations sur l’erreur en question. Par exemple, la version de débogage de Flash Player affiche la boîte de dialogue suivante, qui décrit l’erreur associée à une tentative de chargement d’un fichier par l’application à partir d’une URL non valide : La plupart des événements d’erreur reposent sur la classe ErrorEvent. Ils présentent donc une propriété appelée text, qui sert au stockage du message d’erreur que Flash Player ou AIR affiche. Il existe deux exceptions : les classes StatusEvent et NetStatusEvent. Ces deux classes possèdent une propriété level (StatusEvent.level et NetStatusEvent.info.level). Lorsque la valeur de la propriété level est error, ces types d’événement sont considérés comme des événements d’erreur. Un événement d’erreur n’interrompt pas l’exécution du fichier SWF. Il se traduit uniquement par l’affichage d’une boîte de dialogue dans les versions de débogage des navigateurs et des lecteurs autonomes, d’un message dans le panneau de sortie du lecteur de création et d’une entrée dans le fichier journal d’Adobe Flash Builder. Aucune manifestation n’est visible dans les autres versions de Flash Player ou AIR. Exemple de gestion des événements : Alarm Clock Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’exemple Alarm Clock correspond à une horloge qui permet à l’utilisateur de déterminer l’heure à laquelle l’alarme doit se déclencher et d’afficher un message en même temps. Il repose sur l’application SimpleClock du chapitre « Utilisation des dates et des heures » à la page 1 et illustre de nombreux aspects de l’utilisation des événements dans ActionScript 3.0, notamment les suivants : • Ecoute des événements et réponse • Notification d’un événement aux écouteurs • Créer un type d’événement personnalisé GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 146 Gestion des événements Dernière mise à jour le 27/4/2013 Pour obtenir les fichiers d’application Flash Professional associés à cet exemple, voir www.adobe.com/go/learn_programmingAS3samples_flash_fr. Pour obtenir les fichiers d’application Flex associés à cet exemple, voir http://www.adobe.com/go/as3examples_fr. Les fichiers d’application Alarm Clock se trouvent dans le dossier Samples/AlarmClock. Il s’agit des fichiers suivants : Présentation du réveil Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Dans cet exemple, la principale fonctionnalité de l’horloge (dont la mesure du temps et l’affichage du cadran) réutilise le code de l’application SimpleClock, décrite à la section « Exemple de date et heure : horloge analogique simple » à la page 6. La classe AlarmClock étend la classe SimpleClock de cet exemple en y ajoutant la fonctionnalité de réveil requise : réglage de l’heure de déclenchement et avertissement une fois l’alarme déclenchée. Le rôle des événements est de fournir un avertissement lorsque se produit quelque chose. La classe AlarmClock expose l’événement Alarme, à l’écoute duquel d’autres objets peuvent être placés afin d’effectuer les actions voulues. En outre, la classe AlarmClock utilise une occurrence de la classe Timer pour déterminer à quel moment déclencher l’alarme. Comme la classe AlarmClock, la classe Timer fournit un événement pour avertir d’autres objets (une occurrence de AlarmClock dans ce cas) une fois un certain délai écoulé. Comme dans la plupart des applications ActionScript, les événements constituent une part importante de la fonctionnalité de l’exemple Alarm Clock. Déclenchement de l’alarme Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Comme mentionné plus haut, la seule fonctionnalité de la classe AlarmClock est liée à la définition et au déclenchement de l’alarme. La classe intégrée Timer (flash.utils.Timer) permet au développeur de définir du code qui sera exécuté après un délai spécifique. La classe AlarmClock utilise une occurrence de Timer pour déterminer le moment auquel déclencher l’alarme. Fichier Description AlarmClockApp.mxml ou AlarmClockApp.fla Fichier d’application principal dans Flash (FLA) ou Flex (MXML). com/example/programmingas3/clock/AlarmClock.as Classe permettant d’étendre la classe SimpleClock, qui ajoute la fonctionnalité de réveil. com/example/programmingas3/clock/AlarmEvent.as Une classe d’événement personnalisé (sous-classe de flash.events.Event), qui sert d’objet événement à l’événement alarm de la classe AlarmClock. com/example/programmingas3/clock/AnalogClockFace.as Dessine une horloge ronde et les aiguilles des heures, des minutes et des secondes en fonction de l’heure (décrit dans l’exemple SimpleClock). com/example/programmingas3/clock/SimpleClock.as Composant d’interface d’horloge doté d’une fonctionnalité simple de mesure temporelle (décrit dans l’exemple SimpleClock). GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 147 Gestion des événements Dernière mise à jour le 27/4/2013 import flash.events.TimerEvent; import flash.utils.Timer; /** * The Timer that will be used for the alarm. */ public var alarmTimer:Timer; ... /** * Instantiates a new AlarmClock of a given size. */ public override function initClock(faceSize:Number = 200):void { super.initClock(faceSize); alarmTimer = new Timer(0, 1); alarmTimer.addEventListener(TimerEvent.TIMER, onAlarm); } L’occurrence de Timer définie dans la classe AlarmClock est appelée alarmTimer. La méthode initClock(), qui effectue les opérations de configuration nécessaires à l’occurrence de AlarmClock, exploite la variable alarmTimer de deux manières. Tout d’abord, la variable est instanciée avec les paramètres indiquant à l’occurrence de Timer d’attendre 0 milliseconde et de déclencher l’événement timer une seule fois. Après instanciation de alarmTimer, le code appelle la méthode addEventListener() de cette variable pour indiquer qu’il veut écouter l’événement timer de cette variable. Le fonctionnement d’une occurrence de Timer repose sur la distribution de l’événement timer après un certain délai. La classe AlarmClock doit savoir quand l’événement timer est distribué afin de déclencher sa propre alarme. En appelant addEventListener(), le code AlarmClock s’enregistre comme écouteur auprès de alarmTimer. Les deux paramètres indiquent que la classe AlarmClock souhaite écouter l’événement timer (indiqué par la constante TimerEvent.TIMER), et que lorsque l’événement survient, la méthode onAlarm() de la classe AlarmClock doit être appelée en réponse à l’événement. Pour effectivement définir l’alarme, la méthode setAlarm() de la classe AlarmClock est appelée, comme suit : GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 148 Gestion des événements Dernière mise à jour le 27/4/2013 /** * Sets the time at which the alarm should go off. * @param hour The hour portion of the alarm time. * @param minutes The minutes portion of the alarm time. * @param message The message to display when the alarm goes off. * @return The time at which the alarm will go off. */ public function setAlarm(hour:Number = 0, minutes:Number = 0, message:String = "Alarm!"):Date { this.alarmMessage = message; var now:Date = new Date(); // Create this time on today's date. alarmTime = new Date(now.fullYear, now.month, now.date, hour, minutes); // Determine if the specified time has already passed today. if (alarmTime <= now) { alarmTime.setTime(alarmTime.time + MILLISECONDS_PER_DAY); } // Stop the alarm timer if it's currently set. alarmTimer.reset(); // Calculate how many milliseconds should pass before the alarm should // go off (the difference between the alarm time and now) and set that // value as the delay for the alarm timer. alarmTimer.delay = Math.max(1000, alarmTime.time - now.time); alarmTimer.start(); return alarmTime; } Cette méthode effectue plusieurs opérations, notamment le stockage du message d’alarme et la création d’un objet Date (alarmTime) représentant le moment réel où l’alarme se déclenchera. Point le plus important de cette étude, le minuteur de la variable alarmTimer, dans les dernières lignes la méthode, est défini et activé. Tout d’abord, la méthode reset() est appelée, qui arrête le minuteur et le remet à zéro s’il est déjà reparti. Ensuite, l’heure actuelle (représentée par la variable now) est soustraite à la valeur de la variable alarmTime afin de déterminer combien de millisecondes doivent s’écouler avant le déclenchement de l’alarme. La classe Timer ne déclenche pas l’événement timer à une heure absolue ; c’est ce décalage relatif qui est attribué à la propriété delay d’alarmTimer. Enfin, la méthode start() est appelée pour lancer le minuteur. Une fois le délai spécifié écoulé, alarmTimer distribue l’événement timer. Comme la classe AlarmClock s’est enregistrée comme écouteur auprès de sa méthode onAlarm() pour l’événement timer, lorsque celui-ci survient, onAlarm() est appelée. /** * Called when the timer event is dispatched. */ public function onAlarm(event:TimerEvent):void { trace("Alarm!"); var alarm:AlarmEvent = new AlarmEvent(this.alarmMessage); this.dispatchEvent(alarm); } GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 149 Gestion des événements Dernière mise à jour le 27/4/2013 Lorsqu’une méthode est enregistrée comme écouteur d’événement, elle doit être définie avec la signature adaptée (c’est-à-dire le jeu de paramètres et le type de renvoi de la méthode). Pour écouter l’événement timer de la classe Timer, une méthode doit comporter un paramètre dont le type de données est TimerEvent (flash.event.TimerEvent), une sous-classe de la classe Event. Lorsque l’occurrence de Timer appelle ses écouteurs d’événement, elle transmet une occurrence de TimerEvent à l’objet événement. Notification de l’alarme à d’autres composants Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures De même que la classe Timer, la classe AlarmClock fournit un événement qui permet de transmettre des notifications à d’autres éléments de code lorsque l’alarme se déclenche. Pour qu’une classe puisse utiliser le système de gestion des événements intégré à ActionScript, elle doit implémenter l’interface flash.events.IEventDispatcher. La plupart du temps, cela se fait par extension de la classe flash.events.EventDispatcher, qui assure une implémentation standard de IEventDispatcher (ou par extension de l’une des sous-classes de EventDispatcher). Comme décrit précédemment, la classe AlarmClock étend la classe SimpleClock, qui (par le biais d’une chaîne d’héritage) étend la classe EventDispatcher. Ainsi, la classe AlarmClock intègre déjà une fonctionnalité lui permettant de fournir ses propres événements. D’autres éléments de code peuvent s’enregistrer pour être notifiés de l’événement alarm de la classe AlarmClock en appelant la méthode addEventListener(), héritée de EventDispatcher. Lorsqu’une occurrence de AlarmClock est prête à notifier à d’autres éléments de code le déclenchement de l’événement alarm, elle le fait en appelant la méthode dispatchEvent(), également héritée de EventDispatcher. var alarm:AlarmEvent = new AlarmEvent(this.alarmMessage); this.dispatchEvent(alarm); Ces lignes de code sont extraites de la méthode onAlarm() de la classe AlarmClock (présentée plus haut dans son intégralité). La méthode dispatchEvent() de l’occurrence de AlarmClock est appelée, puis elle notifie à tous les écouteurs enregistrés le déclenchement de l’événement alarm de l’occurrence de AlarmClock. Le paramètre transmis à dispatchEvent() est l’objet événement qui sera ensuite passé aux méthodes d’écouteur. Dans ce cas, il s’agit d’une occurrence de la classe AlarmEvent, une sous-classe de Event créée spécialement pour cet exemple. Elaboration d’un événement d’alarme personnalisé Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Tous les écouteurs d’événement reçoivent un paramètre d’objet événement avec des informations sur l’événement qui a été déclenché. Dans bien des cas, l’objet événement est une occurrence de la classe Event. Dans d’autres cas néanmoins, il s’avère utile de fournir des informations complémentaires aux écouteurs d’événement. Il suffit pour cela de définir une nouvelle classe, sous-classe de la classe Event, et d’utiliser une occurrence de cette classe comme objet événement. Dans cet exemple, une occurrence de AlarmEvent est utilisée comme objet événement lorsque l’événement alarm de la classe AlarmClock est distribué. La classe AlarmEvent, présentée ici, fournit des informations complémentaires sur l’événement alarm, à savoir le message d’alarme : GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 150 Gestion des événements Dernière mise à jour le 27/4/2013 import flash.events.Event; /** * This custom Event class adds a message property to a basic Event. */ public class AlarmEvent extends Event { /** * The name of the new AlarmEvent type. */ public static const ALARM:String = "alarm"; /** * A text message that can be passed to an event handler * with this event object. */ public var message:String; /** *Constructor. *@param message The text to display when the alarm goes off. */ public function AlarmEvent(message:String = "ALARM!") { super(ALARM); this.message = message; } ... } Le meilleur moyen de créer une classe d’objet événement personnalisée est de définir une classe qui étend la classEvent, comme illustré dans l’exemple précédent. Pour compléter la fonctionnalité héritée, la classe AlarmEvent définit une propriété message qui contient le texte du message d’alarme associé à l’événement. La valeur message est transmise sous forme de paramètre au constructeur AlarmEvent. La classe AlarmEvent définit également la constante ALARM qui peut servir à référencer l’événement (alarm) lors de l’appel de la méthode addEventListener() de la classe AlarmClock. Outre l’ajout de fonctionnalité, chaque sous-classe Event doit redéfinir la méthode clone() héritée dans le cadre de la gestion des événements ActionScript. Les sous-classes Event peuvent éventuellement redéfinir la méthode toString() afin d’inclure les propriétés de l’événement personnalisé dans la valeur renvoyée par l’appel de la méthode toString(). GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 151 Gestion des événements Dernière mise à jour le 27/4/2013 /** * Creates and returns a copy of the current instance. * @return A copy of the current instance. */ public override function clone():Event { return new AlarmEvent(message); } /** * Returns a String containing all the properties of the current * instance. * @return A string representation of the current instance. */ public override function toString():String { return formatToString("AlarmEvent", "type", "bubbles", "cancelable", "eventPhase", "message"); } La méthode clone() redéfinie doit renvoyer une nouvelle occurrence de la sous-classe Event personnalisée, avec toutes les propriétés personnalisées définies pour correspondre à l’occurrence actuelle. Dans la méthode toString() redéfinie, la méthode d’utilitaire formatToString() (héritée de Event) sert à fournir une chaîne comportant le nom du type personnalisé, ainsi que les noms et valeurs de toutes ses propriétés. 152 Dernière mise à jour le 27/4/2013 Chapitre 9 : Utilisation de domaines d’application Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le rôle de la classe ApplicationDomain est de stocker un tableau des définitions ActionScript 3.0. L’ensemble du code d’un fichier SWF est défini de sorte à exister dans un domaine d’application. Les domaines d’application servent à partitionner les classes qui se trouvent dans un même domaine de sécurité. Ainsi, plusieurs définitions de la même classe peuvent exister et les enfants peuvent réutiliser les définitions des parents. Vous pouvez faire appel aux domaines d’application lors du chargement, au moyen de l’API de la classe Loader, d’un fichier SWF externe écrit en ActionScript 3.0 (Notez que vous ne pouvez pas utiliser les domaines d’application lorsque vous chargez une image ou un fichier SWF écrit en ActionScript 1.0 ou 2.0.) Toutes les définitions ActionScript 3.0 contenues dans la classe chargée sont stockées dans le domaine d’application. Lorsque vous chargez un fichier SWF, vous devez indiquer que le fichier doit être inclus dans le même domaine d’application que l’objet Loader en attribuant au paramètre applicationDomain de l’objet LoaderContext la valeur ApplicationDomain.currentDomain. Si vous placez le fichier SWF chargé dans le même domaine d’application, vous pourrez accéder directement à ses classes, Cela s’avère pratique si vous chargez un fichier SWF qui contient des médias incorporés auxquels vous pouvez accéder via les noms de classe associés, ou si vous voulez accéder aux méthodes du fichier SWF chargé. L’exemple suivant présuppose l’accès à un fichier Greeter.swf distinct définissant une méthode publique nommée welcome() : GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 153 Utilisation de domaines d’application Dernière mise à jour le 27/4/2013 package { import flash.display.Loader; import flash.display.Sprite; import flash.events.*; import flash.net.URLRequest; import flash.system.ApplicationDomain; import flash.system.LoaderContext; public class ApplicationDomainExample extends Sprite { private var ldr:Loader; public function ApplicationDomainExample() { ldr = new Loader(); var req:URLRequest = new URLRequest("Greeter.swf"); var ldrContext:LoaderContext = new LoaderContext(false, ApplicationDomain.currentDomain); ldr.contentLoaderInfo.addEventListener(Event.COMPLETE, completeHandler); ldr.load(req, ldrContext); } private function completeHandler(event:Event):void { var myGreeter:Class = ApplicationDomain.currentDomain.getDefinition("Greeter") as Class; var myGreeter:Greeter = Greeter(event.target.content); var message:String = myGreeter.welcome("Tommy"); trace(message); // Hello, Tommy } } } Voir aussi l’exemple de classe ApplicationDomain dans le manuel Guide de référence ActionScript 3.0 pour la plateforme Adobe Flash. Voici d’autres points à garder à l’esprit lorsque vous utilisez les domaines d’application : • L’ensemble du code d’un fichier SWF est défini de sorte à exister dans un domaine d’application. L’application principale s’exécute dans le domaine d’application actif. Le domaine du système contient tous les domaines d’application, y compris le domaine actif ; il contient donc toutes les classes Flash Player. • A l’exception du domaine du système, tous les domaines d’application sont associés à un domaine parent. Le domaine parent du domaine de l’application principale est le domaine du système. Les classes chargées ne sont définies que si leur parent ne les définit pas encore. Vous ne pouvez pas remplacer une définition de classe chargée par une définition plus récente. Le schéma suivant illustre une application qui charge du contenu à partir de divers fichiers SWF au sein d’un domaine unique, domain1.com. Selon le contenu chargé, différents domaines d’application peuvent être utilisés. Le texte suivant décrit la logique utilisée pour définir le domaine d’application approprié pour chaque fichier SWF de l’application. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 154 Utilisation de domaines d’application Dernière mise à jour le 27/4/2013 A. Utilisation A B. Utilisation B C. Utilisation C Le fichier principal d’application est application1.swf. Il contient des objets Loader qui chargent du contenu à partir d’autres fichiers SWF. Dans ce scénario, le domaine d’application 1 est actif. Utilisation A, Utilisation B et Utilisation C illustrent les différentes techniques permettant de définir le domaine d’application approprié pour chaque fichier SWF de l’application. Utilisation A Partitionnez le fichier SWF enfant en créant un enfant du domaine du système. Dans le schéma, le domaine d’application 2 est créé en tant qu’enfant du domaine du système. Le fichier application2.swf est chargé dans le domaine d’application 2 et ses définitions de classe sont ainsi partitionnées à partir des classes définies dans application1.swf. Cette technique s’appliquera par exemple lorsqu’une ancienne application doit charger dynamiquement une nouvelle version de la même application sans créer de conflits. Les conflits sont éliminés parce que même si les noms de classe sont les mêmes, ils sont répartis dans différents domaines d’application. Le code suivant crée un domaine d’application qui est un enfant du domaine du système, puis commence à charger un fichier SWF à l’aide de ce domaine d’application : var appDomainA:ApplicationDomain = new ApplicationDomain(); var contextA:LoaderContext = new LoaderContext(false, appDomainA); var loaderA:Loader = new Loader(); loaderA.load(new URLRequest("application2.swf"), contextA); Utilisation B Ajoutez de nouvelles définitions de classe aux définitions actuelles. Le domaine d’application de module1.swf est défini sur le domaine actif (Domaine d’application 1). Vous pouvez alors ajouter au jeu actuel de définitions de classe de l’application de nouvelles définitions de classe. Cela pourrait servir pour une bibliothèque d’exécution partagée appartenant à l’application principale. Le fichier SWF est traité comme une bibliothèque partagée distante (RSL, remote shared library). Utilisez cette technique pour charger des RSL à l’aide d’un fichier de préchargement avant le lancement de l’application. Le code suivant charge un fichier SWF, en définissant son domaine d’application sur le domaine actif : GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 155 Utilisation de domaines d’application Dernière mise à jour le 27/4/2013 var appDomainB:ApplicationDomain = ApplicationDomain.currentDomain; var contextB:LoaderContext = new LoaderContext(false, appDomainB); var loaderB:Loader = new Loader(); loaderB.load(new URLRequest("module1.swf"), contextB); Utilisation C Utilisez les définitions de classe du parent en ajoutant un nouveau domaine enfant au domaine actif. Le domaine d’application de module3.swf est un enfant du domaine actif, qui utilise pour toutes les classes les versions du parent. Cette technique peut s’appliquer à un module d’une application Internet riche (RIA, Rich Internet Application) à plusieurs écrans, qui serait chargé comme enfant de l’application principale et utiliserait les types de cette dernière. Si vous pouvez garantir que toutes les classes sont toujours mises à jour pour rester compatibles avec les anciennes versions et que l’application de chargement est toujours plus récente que les contenus qu’elle charge, les enfants utiliseront les versions des parents. L’utilisation d’un nouveau domaine d’application permet également de décharger toutes les définitions de classe en vue du nettoyage, à condition de veiller à ce qu’il ne subsiste aucune référence au fichier SWF enfant. Cette technique autorise les modules chargés à partager les objets Singleton et les membres de classe statiques de l’objet Loader. Le code suivant crée un domaine enfant dans le domaine actif et commence à charger un fichier SWF à l’aide de ce domaine d’application : var appDomainC:ApplicationDomain = new ApplicationDomain(ApplicationDomain.currentDomain); var contextC:LoaderContext = new LoaderContext(false, appDomainC); var loaderC:Loader = new Loader(); loaderC.load(new URLRequest("module3.swf"), contextC); 156 Dernière mise à jour le 27/4/2013 Chapitre 10 : Programmation de l’affichage Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La programmation des éléments visuels dans Adobe® ActionScript® 3.0 repose sur l’utilisation des objets d’affichage sur la scène. Vous pouvez, par exemple, ajouter, déplacer, supprimer et trier les objets d’affichage, appliquer des filtres et des masques, dessiner des vecteurs et des graphiques bitmap, et exécuter des transformations en trois dimensions par le biais de l’API de programmation de l’affichage ActionScript. Les classes principales permettant de programmer l’affichage font partie du package flash.display. Remarque : Adobe® AIR™ fournit l’objet HTMLoader pour rendre et afficher un contenu HTML. L’objet HTMLLoader effectue le rendu des éléments visuels du DOM HTML en tant qu’objet d’affichage unique. Il est impossible d’accéder directement à chaque élément du DOM par le biais de la hiérarchie de la liste d’affichage ActionScript. Vous accédez aux éléments du DOM à l’aide de l’API DOM distincte proposée par l’objet HTMLLoader. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 157 Programmation de l’affichage Dernière mise à jour le 27/4/2013 Concepts fondamentaux de la programmation de l’affichage Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Chaque application créée par le biais d’ActionScript 3.0 possède une hiérarchie d’objets d’affichage appelée liste d’affichage, comme l’indique l’illustration ci-dessous. La liste d’affichage contient tous les éléments visibles de l’application. Comme le montre cette illustration, les éléments d’affichage se rangent dans un ou plusieurs groupes suivants : • Scène La scène constitue le conteneur de base des objets d’affichage. Chaque application comporte un objet Stage, qui contient tous les objets d’affichage à l’écran. La scène correspond au conteneur de plus haut niveau et domine la hiérarchie de la liste d’affichage : Chaque fichier SWF est associé à une classe ActionScript, appelée classe principale du fichier SWF. Lorsqu’un fichier SWF s’ouvre dans Flash Player ou Adobe AIR, Flash Player ou AIR appelle la fonction constructeur correspondant à la classe et l’occurrence créée (systématiquement un type d’objet d’affichage) est ajoutée en tant qu’enfant de l’objet Stage. La classe principale d’un fichier SWF étend systématiquement la classe Sprite (pour plus d’informations, voir « Avantages de l’utilisation de la liste d’affichage » à la page 162). Vous pouvez accéder à la scène via la propriété stage de toute occurrence de DisplayObject. Pour plus d’informations, voir « Définition des propriétés de la scène » à la page 171. • Objets d’affichage GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 158 Programmation de l’affichage Dernière mise à jour le 27/4/2013 Dans ActionScript 3.0, tous les éléments qui apparaissent à l’écran dans une application sont des types d’objets d’affichage. Le package flash.display comprend une classe DisplayObject, qui correspond à une classe de base étendue par diverses autres classes. Ces autres classes représentent divers types d’objets d’affichage, tels que les formes vectorielles, les clips et les champs de texte, pour n’en citer que quelques-uns. Pour une présentation de ces classes, voir « Avantages de l’utilisation de la liste d’affichage » à la page 162. • Conteneurs d’objets d’affichage Les conteneurs d’objets d’affichage sont des types spéciaux d’objets d’affichage qui, outre leur propre représentation visuelle, peuvent également comporter des objets enfant qui sont aussi des objets d’affichage. La classe DisplayObjectContainer est une sous-classe de la classe DisplayObject. Un objet DisplayObjectContainer peut contenir plusieurs objets d’affichage dans la liste d’enfants correspondante. Par exemple, l’illustration suivante contient un type d’objet DisplayObjectContainer appelé Sprite qui comporte divers objets d’affichage : A. Objet SimpleButton. Ce type d’objet d’affichage possède des états « up », « down » et « over ». B. Objet Bitmap. Dans ce cas de figure, l’objet Bitmap a été chargé à partir d’un JPEG externe via un objet Loader. C. Objet Shape. Le « cadre d’image » contient un rectangle arrondi dessiné dans ActionScript. Un filtre Ombre portée est appliqué à cet objet Shape. D. Objet TextField. Dans le contexte des objets d’affichage, les objets DisplayObjectContainer portent également le nom de conteneurs d’objets d’affichage voire, tout simplement, de conteneurs. Comme indiqué précédemment, la scène est un conteneur d’objets d’affichage. Bien que tous les objets d’affichage visibles héritent leurs caractéristiques de la classe DisplayObject, le type de chacun d’eux correspond à une sous-classe déterminée de la classe DisplayObject. Il existe, par exemple, une fonction constructeur associée à la classe Shape ou à la classe Video, mais aucune fonction constructeur pour la classe DisplayObject. Concepts importants et terminologie La liste de référence suivante contient des termes importants utilisés dans le cadre de la programmation des graphiques ActionScript : Alpha Valeur colorimétrique représentant le montant de transparence (ou, plus précisément, le montant d’opacité) d’une couleur. Ainsi, une couleur dotée d’une valeur de canal alpha de 60 % n’affiche que 60 % de son intensité totale et est transparente à 40 %. Graphique bitmap Graphique défini en termes informatiques sous forme de grille (lignes et colonnes) de pixels de couleur. Les exemples courants de graphiques bitmap incluent les photos numériques et images similaires. A B C D GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 159 Programmation de l’affichage Dernière mise à jour le 27/4/2013 Mode de fondu Indique l’interaction requise du contenu de deux images qui se chevauchent. En règle générale, une image opaque superposée à une autre image se contente de bloquer l’image placée sous elle, qui est donc totalement invisible. Toutefois, divers modes de fondu entraînent le mélange des couleurs de diverses façons de sorte que le résultat corresponde à une combinaison des deux images. Liste d’affichage Hiérarchie des objets d’affichage rendus sous forme de contenu visible à l’écran par Flash Player et AIR. La scène correspond à la racine de la liste d’affichage et tous les objets d’affichage associés à la scène ou à l’un de ses enfants composent la liste d’affichage (même si l’objet n’est pas à proprement parler rendu, parce qu’il réside en dehors de la scène, par exemple). Objet d’affichage Objet représentant un type de contenu visuel dans Flash Player ou AIR. La liste d’affichage ne contient que des objets d’affichage et toutes les classes d’objets d’affichage sont des sous-classes de la classe DisplayObject. Conteneur d’objet d’affichage Type spécial d’objet d’affichage qui, outre (généralement) sa propre représentation visuelle, peut comporter des objets d’affichage enfant. Classe principale du fichier SWF Classe qui définit le comportement de l’objet d’affichage de plus haut niveau d’un fichier SWF, soit, fondamentalement, la classe associée au fichier SWF en tant que tel. Ainsi, dans un fichier SWF généré dans un outil de création Flash, la classe principale correspond à la classe du document. Elle possède un « scénario principal » qui intègre tous les autres scénarios. La classe principale du fichier SWF correspond à la classe dont le scénario principal est une occurrence. Masquage Technique consistant à ne pas afficher certaines parties d’une image (ou, à l’inverse, à n’afficher que certaines parties d’une image). Les sections de l’image masque deviennent transparentes, afin d’assurer la visibilité du contenu sous-jacent. Ce terme se réfère à la bande utilisée par un peintre en bâtiment pour empêcher la peinture d’être appliquée à certaines sections. Scène Conteneur visuel correspondant à la base ou à l’arrière-plan de tout contenu visuel dans un fichier SWF. Transformation Modification des caractéristiques visuelles d’un graphique (rotation de l’objet, modification de son échelle, désalignement, déformation ou altération de sa couleur). Graphique vectoriel Graphique défini en termes informatiques par des lignes et des formes dessinées en fonction de caractéristiques déterminées (épaisseur, longueur, taille, angle et position, par exemple). GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 160 Programmation de l’affichage Dernière mise à jour le 27/4/2013 Classes d’affichage de base Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le package flash.display ActionScript 3.0 contient des classes destinées aux objets visuels susceptibles d’apparaître dans Flash Player ou AIR. L’illustration suivante identifie les relations entre les sous-classes de ces classes d’objets d’affichage de base. L’illustration indique ce dont héritent les classes d’objets d’affichage. Notez que certaines de ces classes, en particulier StaticText, TextField et Video, ne figurent pas dans le package flash.display, mais héritent toutefois des caractéristiques de la classe DisplayObject. Toutes les classes qui étendent la classe DisplayObject héritent de ses méthodes et propriétés. Pour plus d’informations, voir « Propriétés et méthodes de la classe DisplayObject » à la page 165. Vous pouvez créer une occurrence d’un objet des classes suivantes, qui figurent dans le package flash.display : • Bitmap : la classe Bitmap permet de définir des objets bitmap, qu’ils soient chargés à partir de fichiers externes ou rendus via ActionScript. Vous pouvez charger des bitmaps à partir de fichiers externes par le biais de la classe Loader. Libre à vous de charger des fichiers GIF, JPG ou PNG. Vous pouvez également créer un objet BitmapData à partir de données personnalisées, puis créer un objet Bitmap qui utilise ces données. Les méthodes de la classe BitmapData permettent de modifier les bitmaps, qu’ils soient chargés ou créés dans ActionScript. Pour plus d’informations, voir « Chargement d’objets d’affichage » à la page 206 et le chapitre « Utilisation des images bitmap » à la page 251. • Loader : la classe Loader permet de charger des ressources externes (fichiers SWF ou graphiques). Pour plus d’informations, voir « Chargement dynamique du contenu d’affichage » à la page 205. • Shape : la classe Shape permet de créer des graphiques vectoriels, tels que des rectangles, des lignes, des cercles, etc. Pour plus d’informations, voir « Utilisation de l’API de dessin » à la page 230. • SimpleButton : un objet SimpleButton est une représentation ActionScript d’un symbole de bouton créé dans l’outil de programmation Flash. Une occurrence de SimpleButton est dotée de quatre états de bouton : « up », « down », « over » et « hit test » (zone qui réagit aux événements souris et clavier). MorphShape DisplayObject AVM1Movie Shape StaticText Video DisplayObjectContainer TextField Bitmap InteractiveObject SimpleButton Loader Stage MovieClip Sprite GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 161 Programmation de l’affichage Dernière mise à jour le 27/4/2013 • Sprite : un objet Sprite peut contenir des graphiques qui lui sont propres, ainsi que des objets d’affichage enfant (la classe Sprite étend la classe DisplayObjectContainer). Pour plus d’informations, voir « Utilisation de conteneurs d’objets d’affichage » à la page 165 et « Utilisation de l’API de dessin » à la page 230. • MovieClip : un objet MovieClip est la forme ActionScript d’un symbole de clip créé dans l’outil de programmation Flash. En pratique, un objet MovieClip est similaire à un objet Sprite, à une exception près : il possède également un scénario. Pour plus d’informations, voir « Utilisation des clips » à la page 333. Les classes suivantes, qui ne figurent pas dans le package flash.display, sont des sous-classes de la classe DisplayObject : • La classe TextField, qui figure dans le package flash.text, est un objet d’affichage destiné à l’affichage et à la saisie de texte. Pour plus d’informations, voir « Principes de base de l’utilisation du texte » à la page 383. • La classe TextLine, qui figure dans le package flash.text.engine, correspond à l’objet d’affichage permettant d’afficher des lignes de texte composées par Flash Text Engine et Text Layout Framework. Pour plus d’informations, voir « Utilisation de Flash Text Engine » à la page 410 et « Utilisation de Text Layout Framework » à la page 440. • La classe Video, qui figure dans le package flash.media, correspond à l’objet d’affichage utilisé pour afficher des fichiers vidéo. Pour plus d’informations, voir « Utilisation de la vidéo » à la page 489. Les classes suivantes du package flash.display étendent la classe DisplayObject, mais il est impossible d’en créer une occurrence. Parce qu’elles combinent des fonctionnalités communes en une classe unique, elles servent plutôt de classes parent à d’autres objets d’affichage. • AVM1Movie : la classe AVM1Movie permet de représenter des fichiers SWF chargés créés dans ActionScript 1.0 et 2.0. • DisplayObjectContainer : les classes Loader, Stage, Sprite et MovieClip étendent chacune la classe DisplayObjectContainer. Pour plus d’informations, voir « Utilisation de conteneurs d’objets d’affichage » à la page 165. • InteractiveObject : classe de base de tous les objets utilisés pour interagir avec la souris et le clavier. Les objets SimpleButton, TextField, Loader, Sprite, Stage et MovieClip sont tous des sous-classes de la classe InteractiveObject. Pour plus d’informations sur la création d'une interaction de souris ou de clavier, voir « Principes de base de l’interaction utilisateur » à la page 574. • MorphShape : ces objets sont générés lors de la création d’une interpolation de forme dans l’outil de programmation Flash. Il est impossible d’en créer des occurrences par le biais d’ActionScript, mais vous pouvez y accéder dans la liste d’affichage. • Scène : la classe Stage étend la classe DisplayObjectContainer. Il n’existe qu’une seule occurrence de scène par application, et elle figure au sommet de la hiérarchie de la liste d’affichage. Vous pouvez accéder à la scène via la propriété stage de toute occurrence de DisplayObject. Pour plus d’informations, voir « Définition des propriétés de la scène » à la page 171. Par ailleurs, la classe StaticText, qui figure dans le package flash.text, étend la classe DisplayObject, mais il est impossible d’en créer une occurrence dans du code. Les champs de texte statique sont créés dans Flash uniquement. Les classes suivantes ne sont ni des objets d’affichage, ni des conteneurs d’objets d’affichage et n’apparaissent pas dans la liste d’affichage, mais affichent des graphiques sur la scène. Elles dessinent des éléments dans un rectangle, appelé fenêtre d’affichage, positionné relativement à la scène. • StageVideo : la classe StageVideo affiche le contenu vidéo en faisant appel, dans la mesure du possible, à l’accélération matérielle. Cette classe est disponible à partir de Flash Player 10.2. Pour plus d’informations, voir « Présentation à accélération matérielle par le biais de la classe StageVideo » à la page 528. • StageWebView : la classe StageWebView affiche le contenu HTML. Elle est prise en charge depuis la version 2.5 d’AIR. Pour plus d’informations, voir « Objets StageWebView » à la page 1068. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 162 Programmation de l’affichage Dernière mise à jour le 27/4/2013 Les classes fl.display suivantes proposent des fonctionnalités équivalentes à celles des classes flash.display.Loader et LoaderInfo. Utilisez-les au lieu des classes flash.display équivalentes en cas de développement dans l’environnement Flash Professional (CS5.5 ou ultérieur). Dans cet environnement, ces classes permettent de résoudre les problèmes liés à TLF avec préchargement RSL. Pour plus d’informations, voir « Utilisation des classes ProLoader et ProLoaderInfo » à la page 210. • fl.display.ProLoader : équivalente à flash.display.Loader • fl.display.ProLoaderInfo : équivalente à flash.display.LoaderInfo Avantages de l’utilisation de la liste d’affichage Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Dans ActionScript 3.0, des classes distinctes sont réservées aux différents types d’objets d’affichage. Dans ActionScript 1.0 et 2.0, un grand nombre de types d’objets identiques sont inclus dans une même classe : MovieClip. Cette individualisation des classes et la structure hiérarchique des listes d’affichage présentent les avantages suivants : • Rendu plus efficace et utilisation réduite de la mémoire • Gestion optimisée de la profondeur • Parcours entier de la liste d’affichage • Objets d’affichage absents de la liste • Classement simplifié en sous-classes des objets d’affichage Rendu plus efficace et taille réduite des fichiers Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Dans ActionScript 1.0 et 2.0, vous ne pouvez dessiner des formes que dans un objet MovieClip. ActionScript 3.0 intègre des classes d’objets d’affichage plus simples, dans lesquelles vous pouvez dessiner des formes. Parce que ces classes d’objets d’affichage ActionScript 3.0 ne contiennent pas le jeu complet de méthodes et propriétés associées à un objet MovieClip, elles mobilisent moins de ressources en mémoire et processeur. Par exemple, à l’encontre d’un objet Shape, chaque objet MovieClip comporte des propriétés associées au scénario du clip. Les propriétés de gestion du scénario font parfois appel à un volume considérable de ressources en mémoire et processeur. Dans ActionScript 3.0, l’utilisation de l’objet Shape se traduit par une amélioration des performances. L’objet Shape nécessite moins de ressources que l’objet MovieClip, plus complexe. Flash Player et AIR n’ont pas besoin de gérer les propriétés MovieClip inutilisées, optimisant ainsi la vitesse et réduisant les besoins de mémoire de l’objet. Gestion optimisée de la profondeur Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Dans ActionScript 1.0 et 2.0, la profondeur était gérée par un système et des méthodes de gestion linéaire de la profondeur, tels que getNextHighestDepth(). ActionScript 3.0 comprend la classe DisplayObjectContainer, dont les méthodes et propriétés sont mieux adaptées à la gestion de la profondeur des objets d’affichage. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 163 Programmation de l’affichage Dernière mise à jour le 27/4/2013 Dans ActionScript 3.0, lorsque vous déplacez un objet d’affichage au sein de la liste des enfants d’une occurrence de DisplayObjectContainer, les autres enfants du conteneur d’objets d’affichage sont automatiquement repositionnés et des positions d’index enfant appropriées leur sont affectées dans le conteneur d’objets d’affichage. Par ailleurs, ActionScript 3.0 permet systématiquement de détecter tous les objets enfant de tout conteneur d’objets d’affichage. Chaque occurrence de DisplayObjectContainer possède une propriété numChildren, qui indique le nombre d’enfants figurant dans le conteneur d’objets d’affichage. Puisque la liste des enfants d’un conteneur d’objets d’affichage correspond systématiquement à une liste indexée, vous pouvez examiner chaque objet de la liste de la position d’index 0 à la dernière position d’index (numChildren - 1). Cette technique n’était pas proposée par les méthodes et propriétés d’un objet MovieClip dans ActionScript 1.0 et 2.0. ActionScript 3.0 permet de parcourir aisément et séquentiellement la liste d’affichage, car les numéros d’index de la liste des enfants d’un conteneur d’objets d’affichage se suivent. Parcourir la liste d’affichage et gérer la profondeur des objets est désormais beaucoup plus simple que dans ActionScript 1.0 et 2.0. Dans ActionScript 1.0 et 2.0, un clip pouvait en effet contenir des objets dont l’ordre de profondeur n’était pas séquentiel, ce qui rendait parfois le parcours de la liste d’objets difficile. Dans ActionScript 3.0, chaque liste d’enfants d’un conteneur d’objets d’affichage est mise en cache en interne sous forme de tableau, ce qui permet des recherches extrêmement rapides (par index). Passer en boucle sur tous les enfants d’un conteneur d’objets d’affichage s’avère également très rapide. Dans ActionScript 3.0, vous pouvez également accéder aux enfants d’un conteneur d’objets d’affichage par le biais de la méthode getChildByName() de la classe DisplayObjectContainer. Parcours entier de la liste d’affichage Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures ActionScript 1.0 et 2.0 ne vous permettaient pas d’accéder à certains objets, telles les formes vectorielles, dessinées dans l’outil de programmation Flash. Dans ActionScript 3.0, vous pouvez accéder à tous les objets de la liste d’affichage, qu’ils aient été créés en ActionScript ou dans l’outil de programmation Flash. Pour plus d’informations, voir « Parcours de la liste d’affichage » à la page 169. Objets d’affichage absents de la liste Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures ActionScript 3.0 permet de créer des objets d’affichage qui ne figurent pas dans la liste d’affichage visible. Ils portent le nom d’objets d’affichage hors liste. Un objet d’affichage n’est ajouté à la liste d’affichage visible que lorsque vous appelez la méthode addChild() ou addChildAt() d’une occurrence de DisplayObjectContainer qui a déjà été intégrée à la liste d’affichage. Les objets d’affichage hors liste permettent d’assembler des objets d’affichage complexes, tels que ceux qui possèdent plusieurs conteneurs d’objets d’affichage comportant plusieurs objets d’affichage. En n’intégrant pas à la liste des objets d’affichage, vous pouvez assembler des objets complexes sans avoir à effectuer leur rendu. Vous économisez ainsi le temps de traitement correspondant. Vous pouvez alors ajouter un objet hors liste à la liste d’affichage au moment voulu. Il est également possible d’intégrer un enfant d’un conteneur d’objets d’affichage à la liste d’affichage, puis de l’en extraire ou d’en modifier la position dans cette dernière, le cas échéant. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 164 Programmation de l’affichage Dernière mise à jour le 27/4/2013 Classement simplifié en sous-classes des objets d’affichage Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Dans ActionScript 1.0 et 2.0, il était souvent nécessaire d’ajouter de nouveaux objets MovieClip à un fichier SWF pour créer des formes de base ou afficher des bitmaps. Dans ActionScript 3.0, la classe DisplayObject comprend un grand nombre de sous-classes intégrées, telles que Shape et Bitmap. Parce que les classes d’ActionScript 3.0 sont plus spécialisées pour des types spécifiques d’objets, il est plus simple de créer des sous-classes de base des classes intégrées. Par exemple, pour dessiner un cercle dans ActionScript 2.0, vous pourriez créer une classe CustomCircle qui étend la classe MovieClip lors de la création d’une occurrence d’un objet de la classe personnalisée. Néanmoins, cette classe comprendrait également diverses propriétés et méthodes émanant de la classe MovieClip (telles que totalFrames) qui ne s’appliquent pas à elle. Dans ActionScript 3.0, vous pouvez toutefois créer une classe CustomCircle qui étend l’objet Shape et, de ce fait, ne comprend pas les propriétés et méthodes sans rapport contenues dans la classe MovieClip. Le code suivant illustre un exemple de classe CustomCircle : import flash.display.*; public class CustomCircle extends Shape { var xPos:Number; var yPos:Number; var radius:Number; var color:uint; public function CustomCircle(xInput:Number, yInput:Number, rInput:Number, colorInput:uint) { xPos = xInput; yPos = yInput; radius = rInput; color = colorInput; this.graphics.beginFill(color); this.graphics.drawCircle(xPos, yPos, radius); } } Utilisation des objets d’affichage Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Maintenant que vous maîtrisez les bases de la scène, des objets d’affichage, des conteneurs d’objets d’affichage et de la liste d’affichage, cette section contient des informations plus détaillées relatives à l’utilisation des objets d’affichage dans ActionScript 3.0. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 165 Programmation de l’affichage Dernière mise à jour le 27/4/2013 Propriétés et méthodes de la classe DisplayObject Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Tous les objets d’affichage sont des sous-classes de la classe DisplayObject et, de ce fait, héritent des propriétés et méthodes de cette dernière. Les propriétés dont ils héritent correspondent aux propriétés de base qui s’appliquent à tous les objets d’affichage. Par exemple, chaque objet d’affichage possède une propriété x et une propriété y qui indiquent sa position dans son conteneur d’objets d’affichage. Il est impossible de créer une occurrence de DisplayObject à l’aide du constructeur de la classe DisplayObject. Vous devez créer un autre type d’objet (un objet qui est une sous-classe de la classe DisplayObject), tel Sprite, pour créer une occurrence d’objet par le biais de l’opérateur new. Par ailleurs, pour créer une classe d’objet d’affichage personnalisée, vous devez créer une sous-classe de l’une des sous-classes d’objets d’affichage ayant une fonction constructeur utilisable (telle que la classe Shape ou la classe Sprite). Pour plus d’informations, voir la description de la classe DisplayObject dans le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash. Ajout d’objets d’affichage à la liste d’affichage Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lorsque vous créez une occurrence d’un objet d’affichage, elle n’apparaît pas à l’écran (sur la scène) tant que vous ne l’avez pas ajoutée à un conteneur d’objets d’affichage figurant dans la liste d’affichage. Par exemple, dans le code suivant, l’objet myText TextField n’est pas visible si vous omettez la dernière ligne de code. Dans la dernière ligne de code, le mot-clé this doit se référer à un conteneur d’objets d’affichage figurant déjà dans la liste d’affichage. import flash.display.*; import flash.text.TextField; var myText:TextField = new TextField(); myText.text = "Buenos dias."; this.addChild(myText); Lorsque vous ajoutez un élément visuel à la scène, il devient un enfant de cette dernière. Le premier fichier SWF chargé dans une application (tel celui intégré à une page HTML) est automatiquement ajouté en tant qu’enfant de la scène. Il peut s’agir de n’importe quel type d’objet qui étend la classe Sprite. Tout objet d’affichage créé sans utiliser ActionScript (par exemple en ajoutant une balise MXML dans un fichier MXML Flex ou en plaçant un élément sur la scène dans Flash Professional) est ajouté à la liste d’affichage. Bien que vous n’ajoutiez pas ces objets d’affichage par le biais d’ActionScript, vous pouvez y accéder via ActionScript. Par exemple, le code suivant règle la largeur d’un objet appelé button1, qui a été ajouté dans l’outil de programmation (et non via ActionScript) : button1.width = 200; Utilisation de conteneurs d’objets d’affichage Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Si un objet DisplayObjectContainer est supprimé de la liste d’affichage ou s’il est transféré ou transformé d’une autre façon, chaque objet d’affichage de DisplayObjectContainer est également supprimé, transféré ou transformé. Un conteneur d’objets d’affichage correspond à un type d’objet d’affichage et peut être ajouté à un autre conteneur d’objets d’affichage. Par exemple, l’image suivante illustre un conteneur d’objets d’affichage, pictureScreen, qui comporte une forme de contour et quatre autres conteneurs d’objets d’affichage (de type PictureFrame) : GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 166 Programmation de l’affichage Dernière mise à jour le 27/4/2013 A. Forme définissant la bordure du conteneur d’objets d’affichage pictureScreen B. Quatre conteneurs d’objets d’affichage, qui sont des enfants de l’objet pictureScreen Pour qu’un objet d’affichage apparaisse dans la liste d’affichage, vous devez l’ajouter à un conteneur d’objets d’affichage figurant dans la liste d’affichage. A cet effet, vous utilisez la méthode addChild() ou la méthode addChildAt() de l’objet conteneur. Par exemple, sans la dernière ligne du code suivant, l’objet myTextField ne s’afficherait pas : var myTextField:TextField = new TextField(); myTextField.text = "hello"; this.root.addChild(myTextField); Dans cet exemple de code, this.root pointe vers le conteneur d’objets d’affichage MovieClip qui comporte le code. Dans votre propre code, vous pouvez stipuler un autre conteneur. A B GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 167 Programmation de l’affichage Dernière mise à jour le 27/4/2013 Utilisez la méthode addChildAt() pour ajouter l’enfant à une position déterminée de la liste des enfants du conteneur d’objets d’affichage. Ces positions d’index basées sur zéro dans la liste des enfants se réfèrent à l’ordre d’apparition (de l’avant à l’arrière) des objets d’affichage. Considérons par exemple les trois objets d’affichage suivants. Chaque objet a été créé à partir d’une classe personnalisée appelée Ball. L’ordre d’apparition de ces objets d’affichage dans leur conteneur peut être modifié par le biais de la méthode addChildAt(). Considérons par exemple le code qui suit : ball_A = new Ball(0xFFCC00, "a"); ball_A.name = "ball_A"; ball_A.x = 20; ball_A.y = 20; container.addChild(ball_A); ball_B = new Ball(0xFFCC00, "b"); ball_B.name = "ball_B"; ball_B.x = 70; ball_B.y = 20; container.addChild(ball_B); ball_C = new Ball(0xFFCC00, "c"); ball_C.name = "ball_C"; ball_C.x = 40; ball_C.y = 60; container.addChildAt(ball_C, 1); Une fois ce code exécuté, les objets d’affichage sont placés comme suit dans l’objet DisplayObjectContainer container. Notez l’ordre d’apparition des objets. Pour placer un objet en tête de la liste d’affichage, il suffit de l’ajouter à nouveau à celle-ci. Par exemple, après le code précédent, utilisez la ligne de code suivante pour placer ball_A en première position dans la pile : container.addChild(ball_A); Ce code supprime ball_A de son emplacement actuel dans la liste d’affichage de container, et l’ajoute ensuite au sommet de la liste, ce qui a pour effet de le placer en haut de l’empilement d’objets. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 168 Programmation de l’affichage Dernière mise à jour le 27/4/2013 Vous disposez de la méthode getChildAt() pour vérifier l’ordre d’apparition des objets d’affichage. La méthode getChildAt() renvoie les objets enfant d’un conteneur en fonction du numéro d’index transmis. Par exemple, le code suivant révèle le nom des objets d’affichage placés à des positions diverses dans la liste des enfants de l’objet DisplayObjectContainer container : trace(container.getChildAt(0).name); // ball_A trace(container.getChildAt(1).name); // ball_C trace(container.getChildAt(2).name); // ball_B Si vous supprimez un objet d’affichage de la liste des enfants de son conteneur parent, les éléments de la liste ayant un indice plus élevé descendent tous d’une position dans l’index des enfants. Ainsi, si nous reprenons l’exemple précédent, le code ci-après illustre le transfert de l’objet d’affichage qui occupait la position 2 dans l’objet DisplayObjectContainer container vers la position 1 suite à la suppression d’un objet d’affichage occupant une position inférieure dans la liste d’enfants : container.removeChild(ball_C); trace(container.getChildAt(0).name); // ball_A trace(container.getChildAt(1).name); // ball_B Les méthodes removeChild() et removeChildAt() ne suppriment pas entièrement une occurrence d’objet d’affichage. Elles se contentent de la supprimer de la liste des enfants du conteneur. Une autre variable peut continuer à faire référence à l’occurrence (utilisez l’opérateur delete pour supprimer totalement un objet). Un objet d’affichage ne possédant qu’un seul conteneur parent, vous ne pouvez ajouter une occurrence d’objet d’affichage qu’à un seul conteneur d’objets d’affichage. Par exemple, le code suivant indique que l’objet d’affichage tf1 ne peut figurer que dans un seul conteneur (soit, dans ce cas, un Sprite, qui étend la classe DisplayObjectContainer) : tf1:TextField = new TextField(); tf2:TextField = new TextField(); tf1.name = "text 1"; tf2.name = "text 2"; container1:Sprite = new Sprite(); container2:Sprite = new Sprite(); container1.addChild(tf1); container1.addChild(tf2); container2.addChild(tf1); trace(container1.numChildren); // 1 trace(container1.getChildAt(0).name); // text 2 trace(container2.numChildren); // 1 trace(container2.getChildAt(0).name); // text 1 Si vous ajoutez à un conteneur d’objets d’affichage un objet qui est déjà contenu dans un autre conteneur d’objets d’affichage, l’objet sera supprimé de la liste des enfants de ce dernier. Outre les méthodes décrites précédemment, la classe DisplayObjectContainer définit plusieurs méthodes d’utilisation des objets d’affichage enfant, notamment : • contains() : détermine si un objet d’affichage est un enfant d’un objet DisplayObjectContainer. • getChildByName() : extrait un objet d’affichage en fonction de son nom. • getChildIndex() : renvoie la position d’index d’un objet d’affichage. • setChildIndex() : modifie la position d’un objet d’affichage enfant. • removeChildren() : supprime plusieurs objets d’affichage enfants. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 169 Programmation de l’affichage Dernière mise à jour le 27/4/2013 • swapChildren() : permute l’ordre de deux objets d’affichage. • swapChildrenAt() : permute l’ordre de deux objets d’affichage définis en fonction de leur valeur d’index. Pour plus d’informations, voir les entrées pertinentes du manuel Guide de référence ActionScript 3.0 pour la plateforme Adobe Flash. N’oubliez pas qu’un objet d’affichage qui ne figure pas dans la liste d’affichage (donc, qui ne se trouve pas dans un conteneur d’objets d’affichage enfant de la scène) est appelé objet d’affichage hors liste. Parcours de la liste d’affichage Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Comme nous l’avons vu, la liste d’affichage est une structure en arborescence. Au sommet de l’arborescence figure la scène, qui peut comporter plusieurs objets d’affichage. Les objets d’affichage qui sont eux-mêmes des conteneurs d’objets d’affichage peuvent contenir d’autres objets d’affichage, voire des conteneurs d’objets d’affichage. La classe DisplayObjectContainer comporte des propriétés et méthodes de parcours de la liste d’affichage, par le biais des listes d’enfants des conteneurs d’objets d’affichage. Considérons par exemple le code suivant, qui ajoute deux objets d’affichage, title et pict, à l’objet container (qui est un Sprite, et la classe Sprite étend la classe DisplayObjectContainer) : GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 170 Programmation de l’affichage Dernière mise à jour le 27/4/2013 var container:Sprite = new Sprite(); var title:TextField = new TextField(); title.text = "Hello"; var pict:Loader = new Loader(); var url:URLRequest = new URLRequest("banana.jpg"); pict.load(url); pict.name = "banana loader"; container.addChild(title); container.addChild(pict); La méthode getChildAt() renvoie l’enfant de la liste d’affichage à une position d’index déterminée : trace(container.getChildAt(0) is TextField); // true Vous pouvez également accéder aux objets enfant en indiquant leur nom. Chaque objet d’affichage possède un nom, qui est attribué par défaut par Flash Player ou AIR (tel « instance1 ») si vous ne l’attribuez pas vous-même. Par exemple, le code suivant indique comment utiliser la méthode getChildByName() pour accéder à un objet d’affichage enfant portant le nom « banana loader » : trace(container.getChildByName("banana loader") is Loader); // true L’utilisation de la méthode getChildByName() entraîne parfois un ralentissement des performances par rapport à la méthode getChildAt(). Puisque la liste d’affichage d’un conteneur d’objets d’affichage peut contenir d’autres conteneurs d’objets d’affichage en tant qu’objets enfant, vous pouvez parcourir la liste d’affichage complète de l’application sous forme d’arborescence. Par exemple, dans l’extrait de code illustré précédemment, une fois l’opération de chargement de l’objet Loader pict terminée, un objet d’affichage enfant (l’image bitmap) de l’objet pict est chargé. Pour accéder à cet objet d’affichage bitmap, vous pouvez écrire pict.getChildAt(0). Vous pouvez également écrire container.getChildAt(0).getChildAt(0) (puisque container.getChildAt(0) == pict). La fonction suivante génère un extrait trace() en retrait de la liste d’affichage d’un conteneur d’objets d’affichage : function traceDisplayList(container:DisplayObjectContainer,indentString:String = ""):void { var child:DisplayObject; for (var i:uint=0; i < container.numChildren; i++) { child = container.getChildAt(i); trace(indentString, child, child.name); if (container.getChildAt(i) is DisplayObjectContainer) { traceDisplayList(DisplayObjectContainer(child), indentString + "") } } } Adobe Flex Si vous utilisez Flex, notez que cette application définit un grand nombre de classes d’objets d’affichage de composant et que celles-ci priment sur les méthodes d’accès à la liste d’affichage de la classe DisplayObjectContainer. Par exemple, la classe Container du package mx.core prime sur la méthode addChild() et autres méthodes de la classe DisplayObjectContainer (étendue par la classe Container). Dans le cas de la méthode addChild(), la classe primant sur la méthode, vous ne pouvez pas ajouter tous les types d’objets d’affichage à une occurrence de Container dans Flex. La méthode remplacée demande dans ce cas que l’objet enfant ajouté soit de type mx.core.UIComponent. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 171 Programmation de l’affichage Dernière mise à jour le 27/4/2013 Définition des propriétés de la scène Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe Stage annule la plupart des propriétés et méthodes de la classe DisplayObject. Si vous appelez l’une de ces propriétés ou méthodes annulées, Flash Player et AIR renvoient une exception. Par exemple, l’objet Stage ne possède pas de propriété x ou y car, en tant que conteneur principal de l’application, sa position est fixe. Or, les propriétés x et y indiquent la position d’un objet d’affichage par rapport à son conteneur, et puisque la scène ne se trouve pas dans un autre conteneur d’objets d’affichage, ces propriétés seraient inapplicables. Remarque : certaines propriétés et méthodes de la classe Stage sont réservées aux objets d’affichage appartenant au même sandbox de sécurité que le premier fichier SWF chargé. Pour plus d’informations, voir « Sécurité de la scène » à la page 1109. Contrôle de la cadence de lecture Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La propriété framerate de la classe Stage permet de définir la cadence de tous les fichiers SWF chargés dans l’application. Pour plus d’informations, voir le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash. Contrôle de la mise à l’échelle de la scène Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lorsque la portion de l’écran qui représente Flash Player ou AIR est redimensionnée, le moteur d’exécution ajuste automatiquement le contenu de la scène en conséquence. La propriété scaleMode de la classe Stage détermine comment le contenu de la scène est ajusté. Cette propriété peut être réglée sur quatre valeurs distinctes, définies en tant que constantes dans la classe flash.display.StageScaleMode : • StageScaleMode.EXACT_FIT met à l’échelle le fichier SWF de sorte à occuper les nouvelles dimensions de la scène sans tenir compte du format d’origine du contenu. Etant donné que les facteurs d’échelle ne sont pas nécessairement identiques en largeur et en hauteur, le contenu risque de sembler écrasé ou étiré en cas de modification du format de la scène. • StageScaleMode.SHOW_ALL met à l’échelle le fichier SWF de sorte à occuper les nouvelles dimensions de la scène sans modifier le format du contenu. Ce mode de mise à l’échelle affiche la totalité du contenu, mais risque de donner lieu à des bordures de type « boîte aux lettres » similaires aux barres noires qui entourent un film grand écran sur une télévision standard. • StageScaleMode.NO_BORDER met à l’échelle le fichier SWF de sorte à occuper totalement les nouvelles dimensions de la scène sans modifier le format du contenu. Ce mode de mise à l’échelle exploite pleinement la zone d’affichage de la scène, mais risque d’engendrer un recadrage. • StageScaleMode.NO_SCALE : ne met pas à l’échelle le fichier SWF. Si les nouvelles dimensions de la scène sont inférieures aux dimensions d’origine, le contenu est recadré. Si elles leur sont supérieures, l’espace ajouté est vide. Dans le mode de mise à l’échelle StageScaleMode.NO_SCALE uniquement, les propriétés stageWidth et stageHeight de la classe Stage permettent de déterminer les dimensions réelles de la scène redimensionnée, exprimées en pixels. (Dans les autres modes, les propriétés stageWidth et stageHeight renvoient toujours la largeur et la hauteur d’origine du fichier SWF.) De plus, lorsque la propriété scaleMode est définie sur StageScaleMode.NO_SCALE et que le fichier SWF est redimensionné, l’événement resize de la classe Stage est distribué, ce qui vous permet d’effectuer des ajustements en conséquence. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 172 Programmation de l’affichage Dernière mise à jour le 27/4/2013 Définir scaleMode sur StageScaleMode.NO_SCALE permet donc de mieux contrôler l’ajustement du contenu en cas de redimensionnement de la fenêtre. Par exemple, si un fichier SWF contient une vidéo et une barre de contrôle, il peut s’avérer utile de conserver la taille de la barre de contrôle en cas de redimensionnement de la scène et de ne modifier que la taille de la fenêtre de vidéo en fonction du changement de taille de la scène. Ce cas de figure est illustré dans l’exemple suivant : // mainContent is a display object containing the main content; // it is positioned at the top-left corner of the Stage, and // it should resize when the SWF resizes. // controlBar is a display object (e.g. a Sprite) containing several // buttons; it should stay positioned at the bottom-left corner of the // Stage (below mainContent) and it should not resize when the SWF // resizes. import flash.display.Stage; import flash.display.StageAlign; import flash.display.StageScaleMode; import flash.events.Event; var swfStage:Stage = mainContent.stage; swfStage.scaleMode = StageScaleMode.NO_SCALE; swfStage.align = StageAlign.TOP_LEFT; swfStage.addEventListener(Event.RESIZE, resizeDisplay); function resizeDisplay(event:Event):void { var swfWidth:int = swfStage.stageWidth; var swfHeight:int = swfStage.stageHeight; // Resize the main content area var newContentHeight:Number = swfHeight - controlBar.height; mainContent.height = newContentHeight; mainContent.scaleX = mainContent.scaleY; // Reposition the control bar. controlBar.y = newContentHeight; } Définition du mode de mise à l’échelle de la scène pour les fenêtres AIR La propriété scaleMode de la scène indique comment celle-ci met à l’échelle et écrête les objets d’affichage enfant lors d’un redimensionnement de fenêtre. N’utilisez que le mode noScale dans AIR. Lorsque ce mode est activé, la scène n’est pas mise à l’échelle. La taille de la scène est modifiée directement en fonction des limites de la fenêtre. Les objets risquent d’être écrêtés si la taille de la fenêtre est inférieure à sa taille initiale. Les modes de mise à l’échelle de la scène sont adaptés aux environnements tels qu’un navigateur Web qui ne permet pas nécessairement de contrôler la taille ou le format de la scène. Grâce aux modes, vous pouvez sélectionner le cas de figure le moins inadapté lorsque la scène ne correspond pas à la taille ou au format idéal défini par l’application. Dans AIR, vous contrôlez toujours la scène. Par conséquent, modifier la disposition du contenu ou redimensionner la fenêtre assure un meilleur résultat que l’activation de la mise à l’échelle de la scène. GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 173 Programmation de l’affichage Dernière mise à jour le 27/4/2013 Dans le navigateur et la fenêtre AIR initiale, la relation entre la taille de fenêtre et le facteur d’échelle initial est extraite du fichier SWF chargé. Toutefois, lorsque vous créez un objet NativeWindow, AIR choisit une relation arbitraire définie sur 72:1 entre la taille de fenêtre et le facteur d’échelle. Par conséquent, si la fenêtre mesure 72x72 pixels, un rectangle de 10x10 pixels ajouté à la fenêtre est dessiné à la taille correcte (soit 10x10 pixels). Par contre, si la fenêtre mesure 144x144 pixels, un rectangle de 10x10 pixels est mis à l’échelle (soit 20x20 pixels). Si vous préférez utiliser une propriété scaleMode autre que noScale pour une scène de fenêtre, vous pouvez compenser le résultat en définissant le facteur d’échelle de tout objet d’affichage de la fenêtre sur le rapport 72 pixels/largeur et hauteur actuelles de la scène. Le code suivant calcule par exemple le facteur d’échelle requis de l’objet d’affichage client : if(newWindow.stage.scaleMode != StageScaleMode.NO_SCALE){ client.scaleX = 72/newWindow.stage.stageWidth; client.scaleY = 72/newWindow.stage.stageHeight; } Remarque : les fenêtres Flex et HTML définissent automatiquement la propriété scaleMode de la scène sur noScale. Modifier la propriété scaleMode entrave le fonctionnement des mécanismes de mise en forme automatique utilisés dans ces types de fenêtres. Utilisation du mode Plein écran Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le mode plein écran permet de définir la scène d’un film de sorte à remplir totalement le moniteur sans bordure ou menu. La propriété displayState de la classe Stage permet d’activer ou désactiver ce mode pour un fichier SWF. La propriété displayState peut être réglée sur l’une des valeurs définies par les constantes de la classe flash.display.StageDisplayState. Pour activer le mode plein écran, définissez la propriété displayState sur StageDisplayState.FULL_SCREEN : stage.displayState = StageDisplayState.FULL_SCREEN; Pour activer le mode interactif plein écran (nouveauté dans Flash Player 11.3), définissez la propriété displayState sur StageDisplayState.FULL_SCREEN_INTERACTIVE : stage.displayState = StageDisplayState.FULL_SCREEN_INTERACTIVE; Dans Flash Player, le mode plein écran ne peut être activé que via ActionScript en réponse à un clic de souris (clic de bouton droit inclus) ou une frappe de touche. Le contenu AIR qui s’exécute dans le sandbox de sécurité de l’application ne nécessite pas que le mode plein écran soit activé en réponse à une action de l’utilisateur. Pour quitter le mode plein écran, définissez la propriété displayState sur StageDisplayState.NORMAL. stage.displayState = StageDisplayState.NORMAL; Un utilisateur peut également désactiver le mode plein écran en plaçant le focus sur une autre fenêtre ou en utilisant l’une des combinaisons de touches suivantes : la touche Echap (toutes les plates-formes), Contrôle-W (Windows), Commande-W (Mac) ou Alt-F4 (Windows). Activation du mode plein écran dans Flash Player Pour activer le mode plein écran d’un fichier SWF intégré à une page HTML, le code HTML requis pour intégrer Flash Player doit comprendre une balise param et un attribut embed, associés au nom allowFullScreen et à la valeur true, comme suit : GUIDE DU DÉVELOPPEUR D’ACTIONSCRIPT 3.0 174 Programmation de l’affichage Dernière mise à jour le 27/4/2013 Dans l’outil de programmation Flash, choisissez Fichier -> Paramètres de publication, puis dans la boîte de dialogue Paramètres de publication, cliquez sur l’onglet HTML et sélectionnez le modèle Flash seulement - Autorisation du Plein écran. Dans Flex, assurez-vous que le modèle HTML inclut les balises