Retrouvez gratuitement la notice de l'appareil ACTIONSCRIPT 3.0 ADOBE au format PDF.
| Type de produit | Langage de programmation |
|---|---|
| Version | 3.0 |
| Plateformes compatibles | Web, mobile, bureau |
| Fonctionnalités principales | Création d'applications interactives, animations, jeux en ligne, multimédia |
| Environnement de développement | Adobe Flash Builder, Adobe Animate |
| Langage de programmation orienté | Objet |
| Support de la communauté | Forums, documentation officielle, tutoriels en ligne |
| Maintenance et mises à jour | Suivi des mises à jour par Adobe, support pour les versions antérieures |
| Sécurité | Gestion des permissions, sandboxing, mises à jour de sécurité régulières |
| Documentation | Documentation officielle disponible sur le site d'Adobe |
| Exigences système | Compatible avec les principaux systèmes d'exploitation et navigateurs modernes |
Téléchargez la notice de votre Langage de programmation au format PDF gratuitement ! Retrouvez votre notice ACTIONSCRIPT 3.0 - ADOBE et reprennez votre appareil électronique en main. Sur cette page sont publiés tous les documents nécessaires à l'utilisation de votre appareil ACTIONSCRIPT 3.0 de la marque ADOBE.
Conversion de la casse dans des chaînes Exemple de chaîne : ASCII Art
Principes de base de l’utilisation des images bitmap Classes Bitmap et BitmapData Manipulation des pixels
Présentation de l’architecture audio
Utilisation des métadonnées audio Accès aux données audio brutes Capture de l’entrée de son
Utilisation des points de repère et des métadonnées Gestion de l’activité de l’objet NetStream
Gestion de l’état de la caméra
Utilisation de la classe DRMStatusEvent
Utilisation de la classe DRMErrorEvent
Formatage des nombres
Objets partagés Les dates et les heures constituent un type d’informations courant utilisé dans les programmes ActionScript. Par exemple, vous pouvez, entre autres, connaître la date du jour ou calculer combien de temps un utilisateur passe sur un écran particulier. Dans ActionScript, vous pouvez utiliser la classe Date pour représenter un moment unique dans le temps, y compris des informations de date et d’heure. Une occurrence de Date contient des valeurs pour les unités de date et d’heure individuelles (année, mois, date, jour de la semaine, heure, minutes, secondes, millisecondes et fuseau horaire, par exemple). Pour des utilisations plus avancées, ActionScript comprend également la classe Timer que vous pouvez utiliser pour effectuer des actions après un certain délai ou à des intervalles répétés.
Date flash.utils.Timer Dans ActionScript 3.0, toutes les fonctions de gestion des dates calendaires et des heures se concentrent autour de la classe de niveau supérieur Date. Cette classe contient des méthodes et des propriétés qui vous permettent de manier les dates et les heures soit selon le modèle universel coordonné (UTC, Universal Time Coordinated), soit selon le fuseau horaire considéré. L’UTC est une définition normalisée du temps qui correspond essentiellement à l’heure du méridien de Greenwich (GMT, Greenwich Mean Time).
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe Date compte l’une des méthodes constructeur les plus polyvalentes de toutes les classes de base. Vous pouvez l’invoquer de quatre manières différentes. Primo, si aucun paramètre n’est fourni, le constructeur Date() renvoie un objet Date contenant la date et l’heure locale actuelle de votre fuseau horaire. Exemple : var now:Date = new Date();
Utilisation des dates et des heures
// gets a Date one day after the start date of 1/1/1970 var startTime:Date = new Date(millisecondsPerDay);
à l’aide d’une valeur chaîne : var nextDay:Date = new Date("Mon May 1 2006 11:30:00 AM");
Date résultant contiendra une valeur date incorrecte.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous pouvez extraire les valeurs de plusieurs unités temporelles au sein de l’objet Date grâce à des propriétés ou des méthodes de la classe Date. Chacune des propriétés suivantes fournit la valeur d’une unité temporelle de l’objet Date :
• La propriété date, qui correspond au numéro calendaire du jour du mois, de 1 à 31 • La propriété day, qui correspond au jour de la semaine au format numérique, 0 représentant dimanche • La propriété hours, de 0 à 23 • La propriété minutes • La propriété seconds • La propriété milliseconds La classe Date offre en fait plusieurs manières d’obtenir ces valeurs. Vous pouvez par exemple obtenir la valeur month de l’objet Date de quatre manières :
• La propriété monthUTC • La méthode getMonthUTC() Ces quatre solutions sont d’une efficacité équivalente, vous pouvez donc adopter celle qui convient le mieux à votre application. Les propriétés répertoriées ci-dessus représentent toutes des composants de la valeur date totale. Par exemple, la propriété milliseconds ne sera jamais supérieure à 999, puisque si elle atteint 1000, la valeur seconds augmente de 1, la propriété milliseconds se remet à zéro. Si vous voulez obtenir la valeur de l’objet Date en millisecondes depuis le 1er janvier 1970 (UTC), vous pouvez utiliser la méthode getTime(). La méthode setTime(), quant à elle, vous permet de modifier la valeur d’un objet Date existant en millisecondes depuis le 1er janvier 1970 (UTC).
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe Date permet d’additionner et de soustraire des dates et heures. Les valeurs Date sont conservées en interne sous forme de millisecondes. Il est donc nécessaire de convertir les autres valeurs en millisecondes avant de les ajouter ou de les soustraire aux objets Date. Si votre application doit effectuer de nombreuses opérations arithmétiques sur les dates et heures, il peut s’avérer utile de créer des constantes qui conservent les valeurs d’unités temporelles courantes en millisecondes, comme illustré ciaprès : public static const millisecondsPerMinute:int = 1000 * 60; public static const millisecondsPerHour:int = 1000 * 60 * 60; public static const millisecondsPerDay:int = 1000 * 60 * 60 * 24;
// sets the invoice date to today's date var invoiceDate:Date = new Date(); // adds 30 days to get the due date var dueDate:Date = new Date(invoiceDate.getTime() + (30 * millisecondsPerDay)); Les opérations arithmétiques sur les dates et heures sont particulièrement pratiques lorsque vous devez convertir des dates d’un fuseau horaire à un autre. Tel est le rôle de la méthode getTimezoneOffset(), qui renvoie la valeur (en minutes) de décalage entre le fuseau horaire de l’objet Date et le temps UTC. La valeur renvoyée s’exprime en minutes parce que tous les fuseaux horaires ne correspondent pas à une heure ; certains sont décalés d’une demi-heure par rapport aux fuseaux voisins. L’exemple suivant utilise le décalage de fuseau horaire pour convertir une date à partir de l’heure locale en temps UTC. La conversion s’effectue tout d’abord par calcul de la valeur du fuseau horaire en millisecondes, puis par ajustement de la valeur Date selon ce montant : // creates a Date in local time var nextDay:Date = new Date("Mon May 1 2006 11:30:00 AM"); // converts the Date to UTC by adding or subtracting the time zone offset var offsetMilliseconds:Number = nextDay.getTimezoneOffset() * 60 * 1000; nextDay.setTime(nextDay.getTime() + offsetMilliseconds);
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lorsque vous développez des applications à l’aide d’Adobe Flash CS4 Professional, vous avez accès au scénario, qui fournit une progression constante, image par image, au sein de votre application. Toutefois, dans un projet purement ActionScript, vous devez compter sur d’autres mécanismes temporels.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Dans certains langages de programmation, vous devez mettre au point des motifs temporels à l’aide d’instructions en boucle telles que for ou do..while. Les instructions en boucle s’exécutent en général aussi vite que la machine locale le permet, ce qui signifie que l’application sera plus rapide sur certaines machines que sur d’autres. Si votre application doit bénéficier d’un intervalle temporel cohérent, vous devez l’associer à un calendrier ou une horloge réels. Bien des applications, telles que les jeux, les animations, les contrôleurs en temps réel, nécessitent des mécanismes de décompte temporel qui soient cohérents d’une machine à l’autre. La classe Timer d’ActionScript 3.0 offre une solution performante dans ce domaine. Grâce au modèle d’événements ActionScript 3.0, la classe Timer distribue des événements Timer dès qu’un intervalle spécifié est atteint.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour la gestion des fonctions temporelles dans ActionScript 3.0, il est recommandé d’utiliser la classe Timer (flash.utils.Timer), qui permet de distribuer des événements dès qu’un intervalle est atteint.
Pour lancer un minuteur, vous devez d’abord créer une occurrence de la classe Timer et lui indiquer à quelle fréquence elle doit générer un événement Timer et combien de fois elle doit le faire avant de s’arrêter. Par exemple, le code suivant crée une occurrence de Timer qui distribue un événement toutes les secondes pendant 60 secondes : var oneMinuteTimer:Timer = new Timer(1000, 60);
Si l’occurrence de Timer prévoit un nombre fixe d’intervalles, elle distribue également un événement timerComplete (défini par la constante TimerEvent.TIMER_COMPLETE) lorsqu’elle atteint l’intervalle final. Voici un court exemple d’application illustrant la classe Timer en action : package { import flash.display.Sprite; import flash.events.TimerEvent; import flash.utils.Timer; public class ShortTimer extends Sprite { public function ShortTimer() Dernière mise à jour le 27/4/2013
La méthode onTick() affiche simplement le nombre actuel de tics. Après cinq secondes, la méthode onTimerComplete() s’exécute et vous avertit que le temps est écoulé. Si vous exécutez cet exemple, vous devriez voir les lignes suivantes s’afficher dans votre console ou fenêtre de suivi à raison d’une ligne par seconde : tick 1 tick 2 tick 3 tick 4 tick 5 Time's Up!
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures ActionScript 3.0 contient un certain nombre de fonctions temporelles similaires à celles qui étaient disponibles dans ActionScript 2.0. Ces fonctions sont fournies au niveau du package dans le package flash.utils et elles fonctionnent de la même manière que dans ActionScript 2.0. Fonction
Un exemple d’horloge analogique simple illustre ces deux concepts de date et heure :
• Utilisation d’une horloge pour fixer le rythme d’une application Pour obtenir les fichiers d’application de cet exemple, voir www.adobe.com/go/learn_programmingAS3samples_flash_fr. Les fichiers d’application SimpleClock se trouvent dans le dossier Samples/SimpleClock. L’application se compose des fichiers suivants :
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Si l’exemple d’horloge est simple, il est toujours judicieux de bien organiser les applications de manière à faciliter leur extension future. Dans ce but, l’application SimpleClock utilise la classe SimpleClock pour gérer les tâches de démarrage et de mesure temporelle. Elle se sert ensuite d’une autre classe, AnalogClockFace, pour l’affichage réel de l’heure. Voici le code qui définit et initialise la classe SimpleClock (vous remarquerez que dans la version Flash, SimpleClock étend la classe Sprite à la place) : public class SimpleClock extends UIComponent { /** * The time display component. • La propriété ticker, qui est une occurrence de la classe Timer La classe SimpleClock utilise un constructeur par défaut. La méthode initClock() se charge de la véritable configuration, en créant le cadran et en lançant le décompte de l’occurrence de Timer.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les lignes suivantes du code SimpleClock créent le cadran utilisé pour afficher l’heure :
Utilisation des dates et des heures
* Sets up a SimpleClock instance. */ public function initClock(faceSize:Number = 200) Lancement du minuteur Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Une fois le cadran créé, la méthode initClock() définit le minuteur : // creates a Timer that fires an event once per second ticker = new Timer(1000); // designates the onTick() method to handle Timer events ticker.addEventListener(TimerEvent.TIMER, onTick); // starts the clock ticking ticker.start(); Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La plupart du code de la classe AnalogClockFace implique la définition des éléments d’affichage du cadran. Lors de son initialisation, AnalogClockFace dessine un contour circulaire, place des libellés numériques pour chaque heure, puis crée trois objets Shape, un pour l’aiguille des heures, un pour celle des minutes et un pour l’aiguille des secondes de l’horloge. Lorsque l’application SimpleClock s’exécute, elle appelle la méthode AnalogClockFace.draw() toutes les secondes, comme suit : /** * Called by the parent container when the display is being drawn. */ public override function draw():void Dernière mise à jour le 27/4/2013
Les chaînes sont des séries de caractères. ActionScript 3.0 prend en charge les caractères ASCII et Unicode.
String Pour les programmeurs, une « chaîne » est un texte, une suite de lettres, chiffres ou autres caractères qui se suivent et forment une unité représentée par une valeur. Par exemple, la ligne de code suivante crée une variable ayant le type de données String (chaîne) et affecte une valeur de chaîne littérale à cette variable : var albumName:String = "Three for the money";
"Hello" "555-7649" La liste de référence suivante contient des termes importants relatifs aux chaînes : ASCII Système de codage permettant de représenter du texte sous forme de caractères et symboles dans les
Caractère Unité de base d’un texte (lettre ou symbole). Concaténation Ajout bout à bout de plusieurs valeurs de chaîne pour en créer une nouvelle.
Utilisation des chaînes
String Valeur textuelle (séquence de caractères). Littéral (ou « littéral de chaîne ») Valeur chaîne écrite explicitement en code, sous forme de valeur texte encadrée par des guillemets droits simples ou doubles. Sous-chaîne Définit une chaîne qui fait partie d’une autre chaîne. Unicode Système standardisé de codage permettant de représenter du texte sous forme de caractères et symboles dans
écrites existantes.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe String permet de représenter des données de chaîne (texte) en ActionScript 3.0. Les chaînes ActionScript prennent en charge les caractères ASCII et Unicode. La meilleure façon de créer une chaîne est d’utiliser un littéral de chaîne. Pour déclarer un littéral de chaîne, utilisez les guillemets droits doubles (") ou les guillemets droits simples ('). Par exemple, les deux chaînes suivantes sont équivalentes : var str1:String = "hello"; var str2:String = 'hello';
// str3 == "" Chaque caractère d’une chaîne possède une position d’index dans la chaîne (un entier). La position d’index du premier caractère est 0. Par exemple, dans la chaîne suivante, le caractère y occupe la position 0 et le caractère w occupe la position 5 : "yellow"
La fonction globale String() renvoie la même valeur pour un objet donné que la valeur renvoyée par l’objet appelant la méthode toString().
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La concaténation de chaînes consiste à prendre deux chaînes et à les combiner en une seule chaîne de façon séquentielle. Par exemple, vous pouvez utiliser l’opérateur + pour concaténer deux chaînes : var str1:String = "green"; var str2:String = "ish"; var str3:String = str1 + str2; // str3 == "greenish"
Les sous-chaînes sont des caractères consécutifs à l’intérieur d’une chaîne. La chaîne "abc", par exemple, contient les sous-chaînes suivantes : "", "a", "ab", "abc", "b", "bc", "c". Vous pouvez utiliser des méthodes ActionScript pour localiser les sous-chaînes d’une chaîne. Les modèles sont définis en ActionScript par des chaînes ou par des expressions régulières. Par exemple, l’expression régulière suivante définit un modèle spécifique, les lettres A, B, et C suivies d’un chiffre (les barres de fraction sont des délimiteurs d’expression régulière) : /ABC\d/
Les expressions régulières peuvent définir des modèles compliqués. Pour plus d’informations, voir « Utilisation d’expressions régulières » à la page 78.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les méthodes substr() et substring() sont similaires. Elles renvoient toutes les deux une sous-chaîne d’une chaîne. Elles prennent deux paramètres. Dans les deux méthodes, le premier paramètre est la position du caractère initial dans la chaîne concernée. Toutefois, dans la méthode substr(), le deuxième paramètre est la longueur de la sous-chaîne à renvoyer, alors que dans la méthode substring(), le deuxième paramètre est la position du caractère final de la souschaîne (qui ne figure pas dans la chaîne renvoyée). Cet exemple illustre la différence entre ces deux méthodes : var str:String = "Hello from Paris, Texas!!!"; trace(str.substr(11,15)); // output: Paris, Texas!!! trace(str.substring(11,15)); // output: Pari
Vous pouvez utiliser les méthodes indexOf() et lastIndexOf() pour localiser des sous-chaînes correspondantes au sein d’une chaîne, comme dans l’exemple suivant : var str:String = "The moon, the stars, the sea, the land"; trace(str.indexOf("the")); // output: 10
Vous pouvez spécifier un deuxième paramètre pour indiquer la position de l’index dans la chaîne à partir de laquelle commencer la recherche, comme suit : var str:String = "The moon, the stars, the sea, the land" trace(str.indexOf("the", 11)); // output: 21
Vous pouvez utiliser la méthode split() pour créer un tableau de sous-chaînes divisé en fonction d’un caractère délimiteur. Par exemple, vous pouvez segmenter une chaîne séparée par des virgules ou des tabulations en plusieurs chaînes. L’exemple suivant indique comment diviser un tableau en sous-chaînes avec le caractère esperluette (&) comme délimiteur : var queryStr:String = "first=joe&last=cheng&title=manager&StartDate=3/6/65"; var params:Array = queryStr.split("&", 2); // params == ["first=joe","last=cheng"]
Vous pouvez également utiliser une expression régulière comme caractère délimiteur : var str:String = "Give me\t5." var a:Array = str.split(/\s+/); // a == ["Give","me","5."]
Utilisation des chaînes
ActionScript 3.0 pour la plate-forme Adobe Flash.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe String comprend les méthodes suivantes pour utiliser des modèles dans des chaînes :
• Utilisez la méthode replace() pour rechercher des sous-chaînes qui correspondent à un modèle et les remplacer par une sous-chaîne spécifiée. Ces méthodes sont décrites dans les sections suivantes. Vous pouvez utiliser des chaînes ou des expressions régulières pour définir des modèles utilisés dans ces méthodes. Pour plus d’informations sur les expressions régulières, voir « Utilisation d’expressions régulières » à la page 78. Recherche de sous-chaînes correspondantes La méthode search() renvoie la position de l’index de la première sous-chaîne qui correspond à un modèle donné, comme illustré dans cet exemple : var str:String = "The more the merrier."; // (This search is case-sensitive.) trace(str.search("the")); // output: 9
L’exemple suivant présente une expression régulière plus compliquée qui correspond à une chaîne dans des guillemets doubles : var pattern:RegExp = /"[^"]*"/; var str:String = "The \"more\" the merrier."; trace(str.search(pattern)); // output: 4 str = "The \"more the merrier."; trace(str.search(pattern)); // output: -1 // (Indicates no match, since there is no closing double quotation mark.)
Dans cet exemple, les chaînes mises en correspondance ne sont pas sensibles à la casse car l’indicateur i (ignoreCase) est défini dans l’expression régulière, et plusieurs correspondances sont remplacées car l’indicateur g (global) est défini. Pour plus d’informations, voir « Utilisation d’expressions régulières » à la page 78. Vous pouvez inclure les codes de remplacement $ suivants dans la chaîne de remplacement. Le texte de remplacement indiqué dans le tableau suivant est inséré à la place du code de remplacement $ : Code $
• La chaîne complète.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Comme illustré dans l’exemple suivant, les méthodes toLowerCase() et toUpperCase() convertissent les caractères alphabétiques de la chaîne en minuscule et en majuscule, respectivement : var str:String = "Dr. Bob Roberts, #9." trace(str.toLowerCase()); // dr. bob roberts, #9. trace(str.toUpperCase()); // DR. BOB ROBERTS, #9.
(informations d’image dans un fichier de texte séparé par des tabulations).
Le terme ASCII art fait référence à des représentations textuelles d’une image dans lesquelles une grille de polices de caractères à espacement constant (caractères Courier New, par exemple) trace l’image. L’image suivante est un exemple d’ASCII art produit par l’application :
Cet exemple utilise le stockage séparé de données d’application par rapport à l’application ; de cette façon, si les données changent (par exemple, si une autre image est ajoutée ou que le titre d’une image change), il est inutile de recréer le fichier SWF. Dans ce cas, les métadonnées d’image, y compris le titre de l’image, l’URL du fichier d’image réel et certaines valeurs utilisées pour manipuler l’image, sont stockés dans un fichier de texte (le fichier txt/ImageData.txt dans le projet). Le contenu du fichier de texte est le suivant : FILENAMETITLEWHITE_THRESHHOLDBLACK_THRESHHOLD FruitBasket.jpgPear, apple, orange, and bananad810 Banana.jpgA picture of a bananaC820 Orange.jpgorangeFF20 • Le nom d’affichage du bitmap. • Les valeurs de seuil du blanc et les valeurs de seuil du noir pour les bitmaps. Il s’agit de valeurs hexadécimales audessus et en dessous desquelles un pixel doit être considéré comme totalement blanc ou totalement noir. Dès que l’application démarre, la classe AsciiArtBuilder se charge et analyse le contenu du fichier de texte afin de créer la « pile » d’images qu’elle chargera. Pour cela, elle utilise le code suivant de la méthode parseImageInfo() de la classe AsciiArtBuilder :
Utilisation des chaînes
{ var imageInfoRaw:String = lines[i]; Utilisation de méthodes String pour normaliser des titres d’image Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Dans cette application, tous les titres d’image sont affichés à l’aide d’un format standard, avec la première lettre de chaque mot en majuscule (excepté quelques mots qui ne sont généralement pas en majuscule dans des titres anglais). Au lieu de considérer que le fichier de texte contient des titres formatés correctement, l’application formate les titres lors de leur extraction du fichier de texte. Dans la liste de code précédente, lors de l’extraction de valeurs de métadonnées d’image individuelles, la ligne de code suivante est utilisée : imageInfo.title = normalizeTitle(imageProperties[1]);
1 La première lettre du mot est extraite à l’aide de substr(0, 1), qui extraie une sous-chaîne commençant par le
2 Ce caractère est mis en majuscule à l’aide de la méthode toUpperCase().
commençant à l’index 1 (la deuxième lettre) jusqu’à la fin de la chaîne (indiqué en omettant le deuxième paramètre de la méthode substring()). 4 Le dernier mot est créé en combinant la première lettre mise en majuscule et les lettres restantes en utilisant la
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe BitmapToAsciiConverter permet de convertir une image bitmap en sa représentation de texte ASCII. Cette procédure est effectuée par la méthode parseBitmapData(), partiellement représentée ici : var result:String = ""; // Loop through the rows of pixels top to bottom: for (var y:uint = 0; y < _data.height; y += verticalResolution) { // Within each row, loop through pixels left to right: for (var x:uint = 0; x < _data.width; x += horizontalResolution) Dernière mise à jour le 27/4/2013
Vous aurez souvent besoin en programmation d’utiliser un ensemble d’éléments plutôt qu’un seul objet; par exemple, dans une application de lecteur de musique, vous pouvez avoir une liste de morceaux en attente de lecture. Vous ne souhaitez pas créer une variable séparée pour chaque morceau de cette liste. Il serait préférable de rassembler tous les objets Song et de les utiliser sous forme de groupe. Un tableau est un élément de programmation qui agit comme conteneur pour un ensemble d’éléments (une liste de morceaux, par exemple). La plupart du temps, tous les éléments d’un tableau sont des occurrences de la même classe, mais ceci n’est pas obligatoire dans ActionScript. Les éléments individuels d’un tableau sont les éléments du tableau. Un tableau peut être comparé à un tiroir classeur pour des variables. Les variables peuvent être ajoutées en tant qu’éléments au tableau, comme vous placez un dossier dans le tiroir classeur. Vous pouvez utiliser le tableau comme une variable unique, comme si vous transportiez le tiroir entier à un autre endroit. Vous pouvez utiliser les variables en tant que groupe, comme si vous recherchiez des informations dans les dossiers en les parcourant l’un après l’autre. Vous pouvez y accéder individuellement, comme si vous ouvriez le tiroir et sélectionniez un seul dossier. Par exemple, imaginez que vous créez une application de lecteur de musique dans laquelle un utilisateur peut sélectionner plusieurs morceaux et les ajouter à une liste de lecture. Dans votre code ActionScript, vous avez une méthode appelée addSongsToPlaylist() qui accepte un seul tableau comme paramètre. Peu importe le nombre de morceaux à ajouter à la liste (quelques-uns, un grand nombre, ou même un seul), vous devez appeler la méthode addSongsToPlaylist() une seule fois, en lui transmettant le tableau qui contient les objets Song. Dans la méthode addSongsToPlaylist(), vous pouvez utiliser une boucle pour parcourir les éléments (morceaux) du tableau un par un et les ajouter à la liste de lecture. Le type de tableau ActionScript le plus courant est le tableau indexé. Dans un tableau indexé, chaque élément est stocké dans un emplacement numéroté appelé index. On accède à des éléments à l’aide du numéro, comme une adresse. Les tableaux indexés répondent à la plupart des besoins en programmation. La classe Array est une classe courante utilisée pour représenter un tableau indexé.
Utilisation de tableaux
Adobe AIR 1.5. Une utilisation spéciale d’un tableau indexé est un tableau multidimensionnel. Un tableau multidimensionnel est un tableau indexé dont les éléments sont des tableaux indexés, qui contiennent à leur tour d’autres éléments. Le tableau associatif est un autre type de tableau. Il utilise une chaîne key au lieu d’un index numérique pour identifier des éléments individuels. Enfin, ActionScript 3.0 comprend également une classe Dictionary qui représente un dictionnaire. Un dictionnaire est un tableau qui vous permet d’utiliser tout type d’objet comme clé afin de distinguer les éléments entre eux. 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 qui gèrent des tableaux et des vecteurs : Array Objet qui sert de conteneur pour regrouper plusieurs objets. Opérateur ([]) d’accès au tableau Paire de crochets entourant un index ou une clé qui identifie de façon unique un élément du tableau. Cette syntaxe est utilisée après le nom d’une variable de tableau pour spécifier un seul élément du tableau plutôt qu’un tableau entier. Tableau associatif Tableau qui utilise des clés de chaîne pour identifier des éléments individuels. Type de base Type de données des objets qu’une occurrence de Vector est autorisée à stocker. Dictionnaire Tableau dont les éléments sont constitués de paires d’objets appelées clé et valeur. La clé est utilisée à la place d’un index numérique pour identifier un seul élément. Elément Elément unique dans un tableau. Index Adresse numérique utilisée pour identifier un élément unique dans un tableau indexé. Tableau indexé Type de tableau standard qui stocke chaque élément dans une position numérotée et utilise le numéro
Clé Chaîne ou objet utilisé pour identifier un seul élément dans un tableau associatif ou un dictionnaire. Tableau multidimensionnel Tableau contenant des éléments qui sont des tableaux plutôt que des valeurs uniques. T Convention standard utilisée dans la présente documentation pour représenter le type de base d’une occurrence de Vector, quel qu’il soit. La convention T est utilisée pour représenter un nom de classe, comme cela est indiqué dans la description du paramètre Type. (« T » correspond à « type », comme dans « type de données ».) Paramètre Type Syntaxe utilisée avec le nom de classe Vector pour spécifier le type de base de Vector (le type de
Vecteur Type de tableau dont les éléments sont tous des occurrences du même type de données.
Les tableaux indexés stockent une série d’une ou de plusieurs valeurs organisées de façon à ce que vous puissiez accéder à chaque valeur à l’aide d’une valeur d’entier non signé. Le premier index correspond toujours au nombre 0. L’index est ensuite incrémenté d’une unité pour chaque élément ajouté consécutivement au tableau. Dans ActionScript 3.0, deux classes sont utilisées comme tableaux indexés : la classe Array et la classe Vector. Les tableaux indexés utilisent un entier 32 bits non signé pour le numéro d’index. La taille maximale d’un tableau indexé est 232 - 1 ou 4 294 967 295. Si vous tentez de créer un tableau plus grand que la taille maximale, une erreur d’exécution se produit. Pour accéder à un élément particulier d’un tableau indexé, vous pouvez utiliser l’opérateur ([]) d’accès au tableau pour spécifier la position de l’index de l’élément visé. Par exemple, le code suivant représente le premier élément (l’élément à l’index 0) dans un tableau indexé appelé songTitles : songTitles[0]
{ trace("oddNumbers[" + i.toString() + "] = " + oddNumbers[i].toString()); } La classe Vector est un autre type de tableau indexé qui est disponible dans ActionScript 3.0. Une occurrence de Vector est un tableau typé, ce qui signifie que tous les éléments d’une occurrence de Vector ont toujours le même type de données.
Lorsque vous déclarez une variable Vector ou que vous instanciez un objet Vector, vous spécifiez explicitement le type de données des objets que le vecteur peut contenir. Le type de données spécifié est connu sous le nom de type de base du vecteur. Lors de l’exécution et de la compilation (en mode strict), tout code qui fixe la valeur d’un élément Vector ou récupère une valeur d’un élément Vector est contrôlé. Si le type de données de l’objet que l’on tente d’ajouter ou de récupérer ne correspond pas au type de base du vecteur, une erreur se produit. Outre la restriction concernant le type de données, la classe Vector possède d’autres restrictions qui la distinguent de la classe Array :
En raison de ses restrictions, un vecteur présente trois avantages principaux par rapport à une occurrence d’Array dont les éléments sont tous des occurrences d’une classe unique :
A part les contraintes et les avantages supplémentaires, la classe Vector est très proche de la classe Array. Les propriétés et les méthodes d’un objet Vector sont similaires, voire dans certains cas identiques, aux propriétés et aux méthodes d’un objet Array. Au lieu d’utiliser un objet Array dont tous les éléments possèdent le même type de données, il est généralement préférable de faire appel à une occurrence de l’objet Vector.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous pouvez utiliser plusieurs techniques pour créer une occurrence de Array ou une occurrence de Vector. Cependant, les techniques de création de chaque type de tableau sont quelque peu différentes.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous créez un objet Array par l’appel au constructeur Array( ou par l’utilisation d’une syntaxe de littéral de tableau.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures Vous créez une occurrence de Vector par l’appel du constructeur Vector.<T>(). Vous pouvez aussi créer un vecteur par l’appel à la fonction globale Vector.<T>(). Cette fonction convertit un objet spécifié en une occurrence de Vector. Dans Flash Professional CS5 et les versions ultérieures, Flash Builder 4 et les versions ultérieures et Flex 4 et les versions ultérieures, vous pouvez également créer une occurrence de Vector à l’aide de la syntaxe de littéral correspondante. Toutes les fois que vous déclarez une variable Vector (ou de la même façon, un paramètre de la méthode Vector ou un type de renvoi de la méthode Vector), vous spécifiez le type de base de la variable Vector. Vous spécifiez également le type de base lorsque vous créez une occurrence de Vector par l’appel au constructeur Vector.<T>(). Autrement dit, toutes les fois que vous utilisez le terme Vector dans ActionScript, il est accompagné d’un type de base. Vous spécifiez le type de base du vecteur à l’aide de la syntaxe de paramètres de type. Le paramètre de type suit immédiatement le mot Vector dans le code. Il est formé d’un point (.), puis du nom de classe de base entouré de parenthèses en chevron (<>), comme l’indique cet exemple : var v:Vector.<String>; v = new Vector.<String>();
Utilisation du constructeur Vector.<T>() Si vous utilisez le constructeur Vector.<T>() sans arguments, il crée une occurrence de Vector vide. Vous pouvez contrôler qu’un vecteur est vide en vérifiant sa propriété length. Par exemple, le code ci-dessus appelle le constructeur Vector.<T>() sans arguments : var names:Vector.<String> = new Vector.<String>(); trace(names.length); // output: 0
Utilisation du constructeur de syntaxe de littéral Vector Dans Flash Professional CS5 et les versions ultérieures, Flash Builder 4 et les versions ultérieures et Flex 4 et les versions ultérieures, vous pouvez transmettre une liste de valeurs au constructeur Vector<T>() pour stipuler les valeurs initiales du vecteur : // var v:Vector.<T> = new <T>[E0, ..., En-1 ,]; // For example: var v:Vector.<int> = new <int>[0,1,2,];
• La syntaxe ne gère pas la présence d’éléments vides dans le tableau. Une instruction telle que var
• Il est impossible de spécifier si l’occurrence de Vector possède une longueur fixe. Utilisez à cet effet la propriété fixed.
Utilisation de tableaux
Outre le constructeur Vector.<T>() et le constructeur de syntaxe de littéral Vector, vous disposez également de la fonction globale Vector. <T>() pour créer un objet Vector. La fonction globale Vector.<T>() est une fonction de conversion. Lorsque vous appelez la fonction globale Vector.<T>(), vous spécifiez le type de base du vecteur que la méthode renvoie. Vous transmettez un tableau indexé unique (occurrence de Array ou Vector) comme argument. La méthode renvoie alors un vecteur avec le type de base spécifié, contenant les valeurs dans l’argument du tableau source. Le code ci-dessous montre la syntaxe nécessaire pour appeler la fonction globale Vector.<T>(). var friends:Vector.<String> = Vector.<String>(["Bob", "Larry", "Sarah"]);
Lorsque le code appelle la fonction globale Vector.<T>(), si un élément du tableau source est une occurrence d’une sous-classe du type de base spécifié, l’élément est ajouté au vecteur résultant (aucune erreur ne se produit). L’utilisation de la fonction globale Vector.<T>() est en fait le seul moyen de convertir un vecteur avec un type de base T en un vecteur avec un type de base qui est une superclasse de T.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’opérateur ([]) d’accès au tableau constitue le moyen le plus élémentaire d’ajouter un élément à un tableau indexé. Pour définir la valeur d’un élément de tableau indexé, utilisez le nom d’objet Array ou Vector et le numéro d’index du côté gauche d’une instruction d’affectation. songTitles[5] = "Happy Birthday";
Un objet Array vous permet de créer un élément pour tout index. Cependant, avec un objet Vector, vous pouvez affecter uniquement une valeur à un index existant ou à l’index disponible suivant. Celui-ci correspond à la propriété length de l’objet Vector. Utilisez du code comme celui qui est présenté ci-dessous pour ajouter un nouvel élément à un objet Vector de la façon la plus sûre : myVector[myVector.length] = valueToAdd;
élément inséré dans le tableau à l’aide de la méthode push() aura le numéro d’index le plus élevé. La méthode unshift() insère un ou plusieurs éléments au début d’un tableau, qui est toujours au numéro d’index 0. La méthode splice() insère des éléments au niveau d’un index spécifié dans le tableau.
Mars. Deuxièmement, la méthode unshift() est appelée pour insérer l’élément Mercury au début du tableau. Pour finir, la méthode splice() est appelée pour insérer les éléments Venus et Earth après Mercury, mais avant Mars. Le premier élément envoyé à splice(), l’entier 1, indique à l’insertion de débuter à l’index 1. Le deuxième argument envoyé à splice(), l’entier 0, indique qu’aucun élément ne doit être supprimé. Pour finir, les troisième et quatrième arguments envoyés à splice(), Venus et Earth, sont les éléments à insérer. var planets:Array = new Array(); planets.push("Mars"); // array contents: Mars planets.unshift("Mercury"); // array contents: Mercury,Mars planets.splice(1, 0, "Venus", "Earth"); trace(planets); // array contents: Mercury,Venus,Earth,Mars
Remarque : si une propriété fixed de l’objet Vector est définie sur true, le nombre total d’éléments du vecteur reste immuable. Si vous tentez d’ajouter un nouvel élément à un vecteur de longueur fixe à l’aide des techniques décrites ici, une erreur se produit.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Utilisez l’opérateur ([]) d’accès au tableau pour récupérer la valeur d’un élément de la façon la plus simple. Pour récupérer la valeur d’un élément de tableau indexé, utilisez le nom d’objet Array ou Vector et le numéro d’index du côté droit d’une instruction d’affectation. var myFavoriteSong:String = songTitles[3];
élément n’existe. Dans ce cas, un objet Array renvoie la valeur non définie et un vecteur renvoie une exception RangeError. Trois méthodes des classes Array et Vector, pop(), shift() et splice(), vous permettent de supprimer des éléments. La méthode pop() supprime un élément de la fin du tableau. En d’autres termes, elle supprime l’élément au niveau du numéro d’index le plus élevé. La méthode shift() supprime un élément du début du tableau, ce qui signifie qu’elle supprime toujours l’élément au numéro d’index 0. La méthode splice(), qui peut également être utilisée pour insérer des éléments, supprime un nombre arbitraire d’éléments en commençant au numéro d’index indiqué par le premier argument envoyé à la méthode. L’exemple suivant utilise les trois méthodes pour supprimer des éléments d’une occurrence d’Array. Un tableau nommé oceans est créé pour stocker les noms des océans. Certains noms dans le tableau sont des noms de lacs plutôt que des noms d’océans. Ils doivent donc être supprimés. Premièrement, la méthode splice() est utilisée pour supprimer les éléments Aral et Superior, et insérer les éléments Atlantic et Indian. Le premier argument envoyé à splice(), l’entier 2, indique que l’opération doit commencer par le troisième élément dans la liste, qui est à l’index 2. Le deuxième argument, 2, indique que deux éléments doivent être supprimés. Les arguments restants, Atlantic et Indian, sont des valeurs à insérer à l’index 2.
• Le tri est sensible à la casse, ce qui signifie que les majuscules précédent les minuscules. Par exemple, la lettre D précède la lettre b.
élevés (B, par exemple).
• Le tri est basé sur des chaînes, ce qui signifie que les éléments sont convertis en chaînes avant d’être comparés (par exemple, 10 précède 3 car la chaîne "1" a un code de caractère inférieur à celui de la chaîne "3"). Vous pouvez trier votre tableau en ignorant la casse ou par ordre décroissant. Vous pouvez également trier les nombres de votre tableau par ordre numérique plutôt que par ordre alphabétique. La méthode sort() de la classe Array possède un paramètre options qui vous permet de modifier chaque caractéristique de l’ordre de tri par défaut. Les options sont définies par un ensemble de constantes statiques dans la classe Array, comme indiqué dans la liste suivante :
Dernière mise à jour le 27/4/2013
Utilisation de tableaux
En plus du tri de base qui est disponible pour un objet Array, vous pouvez également établir une règle de tri personnalisée. Cette technique est la seule forme de méthode sort() disponible pour la classe Vector. Pour définir un tri personnalisé, vous rédigez une fonction de tri personnalisée et la transmettez comme argument à la méthode sort(). Par exemple, si vous avez une liste de noms dans laquelle chaque élément de liste contient le nom entier d’une personne mais que vous souhaitez trier la liste par nom de famille, vous devez utiliser une fonction de tri personnalisé pour analyser chaque élément et utiliser le nom de famille dans la fonction de tri. Le code suivant indique comment procéder avec une fonction personnalisée utilisée comme paramètre pour la méthode Array.sort() : var names:Array = new Array("John Q. Smith", "Jane Doe", "Mike Jones"); function orderLastName(a, b):int { var lastName:RegExp = /\b\S+$/; var name1 = a.match(lastName); var name2 = b.match(lastName); if (name1 < name2) { return -1; } else if (name1 > name2) La méthode sortOn() est conçue pour des objets Array avec des éléments contenant des objets. Ces objets doivent avoir au moins une propriété en commun pouvant être utilisée comme clé de tri. L’utilisation de la méthode sortOn() pour des tableaux d’autres types provoque des résultats inattendus. Remarque : la classe Vector ne contient pas de méthode sortOn(). Cette méthode n’est disponible que pour les objets Array. L’exemple suivant modifie le tableau poets de façon à ce que chaque élément soit un objet plutôt qu’une chaîne. Chaque objet contient à la fois le nom de famille du poète et sa date de naissance. var poets:Array = new Array(); poets.push({name:"Angelou", born:"1928"}); poets.push({name:"Blake", born:"1757"}); poets.push({name:"cummings", born:"1894"}); poets.push({name:"Dante", born:"1265"}); poets.push({name:"Wang", born:"701"});
Array.NUMERIC est utilisé pour vérifier que le tri est effectué par ordre numérique plutôt que par ordre alphabétique. Ceci est utile même lorsque tous les nombres ont le même nombre de chiffres car vous êtes certain que le tri se fera comme prévu si un nombre comportant un nombre inférieur ou supérieur de chiffres est ensuite ajouté au tableau. poets.sortOn("born", Array.NUMERIC); for (var i:int = 0; i < poets.length; ++i) { trace(poets[i].name, poets[i].born); } /* output: Le tableau renvoyé par les méthodes est un tableau simple de numéros d’index qui reflète le nouvel ordre de tri et ne contient aucun élément du tableau d’origine. Par exemple, pour trier le tableau poets par année de naissance sans le modifier, incluez la constante Array.RETURNINDEXEDARRAY dans l’argument transmis pour le paramètre options. L’exemple suivant stocke les informations d’index renvoyées dans un tableau nommé indices et utilise le tableau indices avec le tableau poets inchangé pour trier les poètes dans l’ordre de leur année de naissance :
Vous pouvez utiliser les méthodes join() et toString() pour interroger le tableau et renvoyer son contenu sous la forme d’une chaîne. Si aucun paramètre n’est utilisé pour la méthode join(), les deux méthodes se comportent de façon identique : elles renvoient une chaîne contenant une liste de tous les éléments du tableau, séparés par une virgule. La méthode join(), contrairement à la méthode toString(), accepte un paramètre nommé delimiter, qui permet de choisir le symbole à utiliser comme séparateur entre chaque élément de la chaîne renvoyée. L’exemple suivant crée un tableau nommé rivers et appelle à la fois join() et toString() pour renvoyer les valeurs dans le tableau sous la forme d’une chaîne. La méthode toString() est utilisée pour renvoyer des valeurs séparées par une virgule (riverCSV), alors que la méthode join() est utilisée pour renvoyer des valeurs séparées par le caractère +. var rivers:Array = ["Nile", "Amazon", "Yangtze", "Mississippi"]; var riverCSV:String = rivers.toString(); trace(riverCSV); // output: Nile,Amazon,Yangtze,Mississippi var riverPSV:String = rivers.join("+"); trace(riverPSV); // output: Nile+Amazon+Yangtze+Mississippi
Un tableau associatif, parfois appelé hachage ou mappage, utilise des clés plutôt qu’un index numérique pour organiser des valeurs stockées. Chaque clé dans un tableau associatif est une chaîne unique qui est utilisée pour accéder à une valeur stockée. Un tableau associatif est une occurrence de la classe Object, ce qui signifie que chaque clé correspond à un nom de propriété. Les tableaux associatifs sont des collections non triées de paires de clés et de valeurs. Votre code ne doit pas s’attendre à ce que les clés d’un tel tableau se présentent dans un ordre précis. ActionScript 3.0 contient aussi un type avancé de tableau associatif appelé dictionnaire. Les dictionnaires, qui sont des occurrences de la classe Dictionary dans le package flash.utils, utilisent des clés de tout type de données. En d’autres termes, les clés de dictionnaire ne sont pas limitées à des valeurs de type String.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Deux méthodes permettent de créer des tableaux associatifs dans ActionScript 3.0. La première consiste à utiliser une occurrence de Object. Celle-ci vous permet d’initialiser votre tableau avec un littéral d’objet. Une occurrence de la classe Object, également appelée objet générique, fonctionne comme un tableau associatif. Chaque nom de propriété de l’objet générique devient la clé qui permet d’accéder à une valeur stockée. L’exemple suivant crée un tableau associatif appelé monitorInfo, à l’aide d’un littéral d’objet pour initialiser le tableau avec deux paires de clés et de valeurs : var monitorInfo:Object = {type:"Flat Panel", resolution:"1600 x 1200"}; trace(monitorInfo["type"], monitorInfo["resolution"]); // output: Flat Panel 1600 x 1200
// output: 16:10 16.7 million
// output: Flat Panel 1600 x 1200
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous pouvez utiliser la classe Dictionary pour créer un tableau associatif qui utilise des objets pour les clés au lieu de chaînes. Ces tableaux sont parfois appelés dictionnaires, hachages ou mappages. Par exemple, supposez que vous avez une application qui détermine l’emplacement d’un objet Sprite selon son association avec un conteneur spécifique. Vous pouvez utiliser un objet Dictionary pour mapper chaque objet Sprite à un conteneur. Le code suivant crée trois occurrences de la classe Sprite qui servent de clés pour l’objet Dictionary. La valeur GroupA ou GroupB est affectée à chaque clé. Les valeurs peuvent être de n’importe quel type de données, mais dans cet exemple, GroupA et GroupB sont des occurrences de la classe Object. Vous pouvez ensuite accéder à la valeur associée à chaque clé avec l’opérateur d’accès au tableau ([]), comme illustré dans le code suivant :
Tant que des références à l’objet existent, le système de nettoyage ne récupère pas la mémoire que l’objet occupe. Si la valeur de myObject est modifiée et qu’elle pointe vers un autre objet ou qu’elle est définie sur null, la mémoire occupée par l’objet d’origine peut être nettoyée. Néanmoins, aucune autre référence à l’objet d’origine ne doit exister. Si vous utilisez myObject comme clé dans un objet Dictionary, vous créez une autre référence à l’objet d’origine. Par exemple, le code suivant crée deux références à un objet, la variable myObject et la clé dans l’objet myMap : import flash.utils.Dictionary; var myObject:Object = new Object(); var myMap:Dictionary = new Dictionary(); myMap[myObject] = "foo";
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les tableaux multidimensionnels contiennent d’autres tableaux comme éléments. Prenons par exemple une liste de tâches stockée sous forme de tableau indexé de chaînes :
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lorsque vous utilisez deux tableaux indexés, vous pouvez visualiser le résultat sous forme de tableau ou de feuille de calcul. Les éléments du premier tableau représentent les lignes alors que les éléments du second tableau représentent les colonnes. Par exemple, le tableau multidimensionnel suivant utilise deux tableaux indexés pour suivre des listes de tâches pour chaque jour de la semaine. Le premier tableau, masterTaskList, est créé à l’aide du constructeur de classe Array. Chaque élément du tableau représente un jour de la semaine, avec l’index 0 représentant lundi et l’index 6 dimanche. Ces éléments peuvent être considérés comme les lignes du tableau. Vous pouvez créer la liste de tâches de chaque jour en affectant un littéral de tableau à chacun des sept éléments que vous créez dans le tableau masterTaskList. Les littéraux de tableau représentent les colonnes du tableau. var masterTaskList:Array = new Array(); masterTaskList[0] = ["wash dishes", "take out trash"]; masterTaskList[1] = ["wash dishes", "pay bills"]; masterTaskList[2] = ["wash dishes", "dentist", "wash dog"]; masterTaskList[3] = ["wash dishes"]; masterTaskList[4] = ["wash dishes", "clean house"]; masterTaskList[5] = ["wash dishes", "wash car", "pay rent"]; masterTaskList[6] = ["mow lawn", "fix chair"];
Le premier groupe de crochets représente le jour de la semaine et le second la liste de tâches pour ce jour. Par exemple, pour récupérer la seconde tâche de la liste du mercredi, utilisez d’abord l’index 2 pour mercredi puis utilisez l’index 1 pour la seconde tâche dans la liste. trace(masterTaskList[2][1]); // output: dentist
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour faciliter l’accès aux tableaux, vous pouvez utiliser un tableau associatif pour les jours de la semaine et un tableau indexé pour les listes de tâche. Les tableaux associatifs vous permettent d’utiliser une syntaxe à point lorsque vous vous référez à un jour particulier de la semaine, mais nécessitent un traitement d’exécution supplémentaire pour accéder à chaque élément du tableau associatif. L’exemple suivant utilise un tableau associatif comme base d’une liste de tâches, avec une paire de clés et de valeurs pour chaque jour de la semaine :
Dans une copie en profondeur, les objets se trouvant dans le tableau d’origine sont copiés également de façon à ce que le nouveau tableau ne pointe pas vers les mêmes objets que le tableau d’origine. La copie en profondeur exige plus d’une ligne de code, ce qui nécessite généralement la création d’une fonction. Une telle fonction peut être créée comme fonction d’utilitaire globale ou comme méthode d’une sous-classe Array. L’exemple suivant définit une fonction appelée clone() qui effectue une copie en profondeur. L’algorithme est issu d’une technique de programmation Java courante. La fonction crée une copie en profondeur en sérialisant le tableau en une occurrence de la classe ByteArray puis en relisant le tableau dans un nouveau tableau. Cette fonction accepte un objet de façon à ce qu’il puisse être utilisé à la fois avec des tableaux indexés et des tableaux associatifs, comme indiqué dans le code suivant :
La classe Array est l’une des classes de base non finale, c’est-à-dire que vous pouvez créer votre sous-classe d’Array. Cette section décrit comment créer une sous-classe d’Array et décrit les problèmes pouvant se poser pendant le processus. Comme mentionné précédemment, les tableaux dans ActionScript ne sont pas typés, mais vous pouvez créer une sousclasse d’Array qui accepte des éléments d’un seul type de données. L’exemple fourni dans les sections suivantes définit une sous-classe Array appelée TypedArray qui limite ses éléments à des valeurs du type de données indiqué dans le premier paramètre. La classe TypedArray est présentée comme un exemple de la façon dont la classe Array est étendue et risque de ne pas être adaptée à des fins de production pour différentes raisons. Premièrement, la vérification du type a lieu lors de l’exécution plutôt que de la compilation. Deuxièmement, lorsqu’une méthode TypedArray rencontre une incompatibilité, elle est ignorée et aucune exception n’est renvoyée, même si vous pouvez facilement modifier les méthodes pour renvoyer des exceptions. Troisièmement, la classe ne peut pas empêcher l’utilisation de l’opérateur d’accès au tableau pour insérer des valeurs de n’importe quel type dans le tableau. Quatrièmement, le style de codage privilégie la simplicité par rapport à l’optimisation des performances. Remarque : vous pouvez utiliser la technique décrite ici pour créer un tableau typé. Cependant, utiliser un objet Vector constitue une meilleure démarche. Une occurrence de Vector est un véritable tableau typé. Elle dépasse la classe Array ou toute sous-classe par ses performances et ses améliorations. Une illustration de la création d’une sous-classe Array constitue l’objet de cette description. Déclaration de la sous-classe Utilisez le mot-clé extends pour indiquer qu’une classe est une sous-classe d’Array. Une sous-classe d’Array doit utiliser l’attribut dynamic, comme la classe Array. Autrement, votre sous-classe ne fonctionne pas correctement. Le code suivant représente la définition de la classe TypedArray, qui comporte une constante contenant le type de données, une méthode de constructeur et les quatre méthodes permettant d’ajouter des éléments au tableau. Le code pour chaque méthode est omis dans cet exemple, mais il est décrit de façon détaillée dans les sections qui suivent :
Le constructeur de sous-classe pose un défi intéressant car il doit accepter une liste d’arguments de longueur arbitraire. Il s’agit de savoir comment transférer les arguments au superconstructeur pour créer le tableau. Si vous transmettez la liste des arguments sous forme d’un tableau, le superconstructeur le considère comme un seul argument de type Array et le tableau résultant a toujours une longueur d’1 élément. Le transfert de listes d’arguments se fait généralement au moyen de la méthode Function.apply(), qui prend un tableau d’arguments comme second paramètre mais le convertit en une liste d’arguments lors de l’exécution de la fonction. Malheureusement, vous ne pouvez pas utiliser la méthode Function.apply() avec des constructeurs. La seule solution est de recréer la logique du constructeur Array dans le constructeur TypedArray. Le code suivant indique l’algorithme utilisé dans le constructeur de classe Array, que vous pouvez réutiliser dans votre constructeur de sous-classe Array :
Dernière mise à jour le 27/4/2013
éléments qui ne sont pas du type de données correct. Chaque méthode appelle ensuite sa version de superclasse. La méthode push() parcourt en boucle la liste des arguments avec une boucle for..in et effectue une vérification du type sur chaque argument. Les arguments qui ne sont pas de type correct sont supprimés du tableau args avec la méthode splice(). Une fois que la boucle for..in se termine, le tableau args contient des valeurs de type dataType uniquement. La version de superclasse de push() est ensuite appelée avec le tableau args mis à jour, comme indiqué dans le code suivant : AS3 override function push(...args):uint { for (var i:* in args) { if (!(args[i] is dataType)) Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’exemple PlayList présente les techniques d’utilisation des tableaux, dans le contexte d’une application de lecture musicale qui gère une liste de chansons. Ces techniques sont les suivantes :
• Ajout d’éléments à un tableau indexé • Tri d’un tableau d’objets en fonction de différentes propriétés, à l’aide d’options de tri différentes • Conversion d’un tableau en une chaîne séparée par des caractères Pour obtenir les fichiers d’application de cet exemple, voir www.adobe.com/go/learn_programmingAS3samples_flash_fr. Les fichiers d’application PlayList se trouvent dans le dossier Samples/PlayList. L’application se compose des fichiers suivants : Fichier
La classe PlayList gère un ensemble d’objets Song. Elle a des méthodes publiques qui permettent d’ajouter une chanson à la liste de lecture (la méthode addSong()) et de trier les chansons dans la liste (la méthode sortList()). En outre, la classe comprend une propriété d’accesseur en lecture seule, songList, qui permet d’accéder au groupe de chansons dans la liste de lecture. En interne, la classe PlayList conserve une trace de ses chansons à l’aide d’une variable Array privée : public class PlayList { private var _songs:Array; private var _currentSort:SortProperty = null; private var _needToSort:Boolean = false; ... } Lorsqu’un utilisateur ajoute une nouvelle chanson dans l’application, le code dans le formulaire de saisie des données appelle la méthode addSong() de la classe PlayList. /** * Adds a song to the playlist. */ public function addSong(song:Song):void Tri de la liste de chansons Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Etant donné que les occurrences Song gérées par la liste de lecture sont des objets complexes, les utilisateurs de l’application peuvent trier la liste de lecture en fonction de différentes propriétés (titre de la chanson ou année de publication, par exemple). Dans l’application PlayList, le tri de la liste des chansons s’effectue en trois étapes : identification de la propriété sur laquelle est basé le tri de la liste, indication des options de tri à utiliser lors du tri en fonction de cette propriété et exécution du tri.
Un objet Song conserve la trace de plusieurs propriétés, notamment le titre de la chanson, l’artiste, l’année de publication, le nom du fichier et un ensemble de genres sélectionné par l’utilisateur auquel la chanson appartient. Seules les trois premières propriétés sont pratiques pour le tri. Dans un souci de commodité pour les développeurs, l’exemple inclut la classe SortProperty, qui agit comme une énumération avec des valeurs représentant les propriétés disponibles pour le tri. public static const TITLE:SortProperty = new SortProperty("title"); public static const ARTIST:SortProperty = new SortProperty("artist"); public static const YEAR:SortProperty = new SortProperty("year");
// Set the initial sorting. this.sortList(SortProperty.TITLE);
Tri par propriété et définition d’options de tri La classe PlayList trie la liste de chansons dans la méthode sortList(), comme suit : /** * Sorts the list of songs according to the specified property. */ public function sortList(sortProperty:SortProperty):void Une fois que vous avez déterminé la propriété et les options de tri, le tableau _songs est trié en appelant sa méthode sortOn(), en transmettant ces deux valeurs comme paramètres. La propriété de tri est enregistrée et la liste des
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Cet exemple utilise non seulement un tableau pour conserver la liste des chansons dans la classe PlayList mais également des tableaux dans la classe Song pour gérer la liste des genres auxquels une chanson appartient. Considérons ce fragment de code issu de la définition de la classe Song : private var _genres:String; public function Song(title:String, artist:String, year:uint, filename:String, genres:Array) { ... // Genres are passed in as an array De la même façon, les accesseurs genres permettent de définir ou de récupérer des genres sous la forme d’un tableau : public function get genres():Array { // Genres are stored as a semicolon-separated String, // so they need to be transformed into an Array to pass them back out. return this._genres.split(";"); Cependant, la gestion des erreurs est une catégorie large qui englobe la réponse à de nombreux types d’erreurs générées lors de la phase de compilation ou lors de l’exécution d’une application. Nous allons passer en revue la gestion des erreurs d’exécution (renvoyées lors de l’exécution d’une application), les différents types d’erreurs générés et les avantages du système de gestion des erreurs d’ActionScript 3.0.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Une erreur d’exécution est une erreur qui se produit dans votre code ActionScript et qui empêche le contenu ActionScript de s’exécuter comme prévu. Pour assurer l’exécution correcte du code ActionScript du point de vue de l’utilisateur, écrivez le code dans l’application qui gère l’erreur (la corrige, la contourne ou informe au moins l’utilisateur qu’elle a eu lieu). Ce processus est appelé gestion des erreurs. La gestion des erreurs est une catégorie large qui englobe la réponse à de nombreux types d’erreurs générées lors de la phase de compilation ou lors de l’exécution d’une application. Les erreurs qui se produisent lors de la compilation sont souvent plus faciles à identifier. Corrigez-les pour terminer la création d’un fichier SWF. Les erreurs d’exécution peuvent être difficiles à détecter car elles se produisent lorsque le code erroné est exécuté. Si un segment de votre programme contient plusieurs branches de code, telle une instruction if..then..else, testez toutes les conditions possibles, avec toutes les valeurs en entrée susceptibles d’être utilisées par un utilisateur réel, pour confirmer que le code ne contient pas d’erreur. Les erreurs d’exécution peuvent être divisées en deux catégories : les erreurs de programme sont des erreurs dans votre code ActionScript (spécification du type de données incorrect pour un paramètre de méthode, par exemple) ; les erreurs logiques sont des erreurs dans la logique (le contrôle des données et la manipulation des valeurs) de votre programme (utilisation de la formule incorrecte pour calculer les taux d’intérêt dans une application bancaire, par exemple). Encore une fois, ces deux types d’erreurs peuvent souvent être détectés et corrigés à l’avance en testant attentivement votre application. Il serait idéal d’identifier et de supprimer toutes les erreurs de votre application avant de la mettre à la disposition des utilisateurs finaux. Cependant, toutes les erreurs ne peuvent pas être prévues ni évitées. Supposons, par exemple, que l’application ActionScript charge des informations depuis un site Web particulier sur lequel vous n’avez aucun contrôle. Si ce site Web n’est pas disponible, la partie de l’application qui dépend de ces données externes ne se comporte pas correctement. L’aspect primordial de la gestion des erreurs consiste à anticiper ces cas de figure et à les traiter judicieusement. Il est préférable que l’exécution de l’application ne soit pas interrompue ou, tout du moins, qu’un message indique à l’utilisateur pourquoi elle ne fonctionne pas.
Pour déterminer si une méthode donnée peut déclencher une erreur ou un événement d’erreur, voir la rubrique correspondante dans le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash. Concepts importants et terminologie La liste de référence suivante contient des termes importants relatifs à la programmation de routines de gestion des erreurs : Asynchrone Commande de programme telle qu’un appel de méthode qui ne fournit pas un résultat immédiat, mais qui produit un résultat (ou une erreur) sous la forme d’un événement. Capture Lorsqu’une exception (une erreur d’exécution) se produit et que votre code la découvre, ce dernier la capture.
Version de débogage Version spéciale du moteur d’exécution Flash, telle que la version de débogage de Flash Player ou l’application de débogage du lanceur AIR (ADL), qui contient le code requis pour avertir les utilisateurs de la présence d’erreurs d’exécution. Dans la version standard de Flash Player ou Adobe AIR (celle que possèdent la plupart des utilisateurs), les erreurs qui ne sont pas gérées par votre code ActionScript sont ignorées. Dans les versions de débogage (intégrées à Adobe Flash CS4 Professional et Adobe Flash Builder), un message d’avertissement apparaît lorsqu’une erreur non gérée se produit. Exception Erreur qui se produit lorsqu’une application est en cours d’exécution et que le moteur d’exécution Flash ne peut pas la résoudre seul. Renvoi Lorsque votre code capture une exception, le moteur d’exécution Flash cesse de signaler l’exception à d’autres objets. S’il est important pour d’autres objets que l’exception leur soit signalée, le code doit renvoyer l’exception pour recommencer le processus de notification. Synchrone Commande de programme (un appel de méthode, par exemple) qui fournit un résultat immédiat (ou qui
Envoi Le fait de signaler au moteur d’exécution Flash (et par conséquent, à d’autres objets et au code ActionScript)
• Erreurs d’exécution : générées lorsque vous exécutez votre application après l’avoir compilée. Les erreurs d’exécution représentent des erreurs qui se produisent lors de la lecture d’un fichier SWF dans un moteur d’exécution Flash tel qu’Adobe Flash Player ou Adobe AIR. Dans la plupart des cas, il est possible de gérer les erreurs d’exécution au moment où elles se produisent, de les signaler à l’utilisateur et de prendre les mesures requises pour poursuivre l’exécution de l’application. S’il s’agit d’une erreur grave (impossibilité de se connecter à un site Web distant ou de charger des données), vous pouvez utiliser la gestion des erreurs pour mettre fin à l’application en douceur.
Par exemple, l’extrait de code suivant renvoie une erreur d’exécution, car la méthode browse() n’est pas appelée avant que le programme ne tente de charger un fichier : var fileRef:FileReference = new FileReference(); try { fileRef.upload(new URLRequest("http://www.yourdomain.com/fileupload.cfm")); } catch (error:IllegalOperationError) { trace(error); • Les erreursasynchrones sont des erreurs du moteur d’exécution qui se produisent hors du flux normal du programme. Elles génèrent des événements, interceptés par des écouteurs d’événement. Une opération asynchrone est une opération dans laquelle une fonction lance une opération mais n’attend pas qu’elle se termine. Vous pouvez créer un écouteur d’événements d’erreur pour attendre que l’application ou l’utilisateur tente une opération. Si cette dernière échoue, vous interceptez l’erreur avec un écouteur d’événements et répondez à l’événement d’erreur. Ensuite, l’écouteur d’événement appelle une fonction de gestionnaire d’événement pour répondre à l’événement d’erreur avec pertinence. Par exemple, le gestionnaire d’événement peut lancer une boîte de dialogue qui invite l’utilisateur à résoudre l’erreur.
événements. Par exemple, au démarrage d’un chargement, l’événement open est distribué. A la fin du chargement, l’événement complete est distribué. Etant donné que la gestion d’événements est asynchrone (c’est-à-dire qu’elle n’a pas lieu à des moments prédéfinis, connus et spécifiques), faites appel à la méthode addEventListener() pour détecter ces événements spécifiques, comme l’indique le code suivant : var fileRef:FileReference = new FileReference(); fileRef.addEventListener(Event.SELECT, selectHandler); fileRef.addEventListener(Event.OPEN, openHandler); fileRef.addEventListener(Event.COMPLETE, completeHandler); fileRef.browse(); function selectHandler(event:Event):void { trace("...select..."); var request:URLRequest = new URLRequest("http://www.yourdomain.com/fileupload.cfm"); request.method = URLRequestMethod.POST; event.target.upload(request); } function openHandler(event:Event):void { trace("...open..."); Lorsqu’il se produit une erreur non interceptée, le moteur d’exécution distribue un événement uncaughtError. Cet événement porte également le nom de « gestionnaire d’erreur global ». Il est distribué par l’objet UncaughtErrorEvents du fichier SWF et est proposé par la propriété LoaderInfo.uncaughtErrorEvents. Si aucun écouteur n’est enregistré pour l’événement uncaughtError, le moteur d’exécution ignore les erreurs non interceptées et tente de poursuivre son exécution, dès lors que l’erreur n’interrompt pas le fichier SWF. Outre la distribution de l’événement uncaughtError, les versions de débogage du moteur d’exécution de Flash répondent aux erreurs non interceptées en mettant fin au script actif. Elles affichent ensuite les erreurs non interceptées dans le résultat de l’instruction trace ou écrivent le message d’erreur dans un fichier journal. Si l’objet exception est une occurrence de la classe Error ou de l’une de ses sous-classes, les informations de trace de la pile s’affichent également dans le résultat. Pour plus d’informations sur l’utilisation de la version de débogage des moteurs d’exécution Flash, voir « Utilisation des versions de débogage des moteurs d’exécution Flash » à la page 58. Remarque : lors du traitement d’un événement uncaughtError, si un événement d’erreur est renvoyé par un gestionnaire uncaughtError, celui-ci est appelé plusieurs fois. Il se produit alors une boucle infinie d’exceptions. Il est donc recommandé d’éviter ce type de scénario.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Etant donné que de nombreuses applications peuvent être exécutées sans créer de logique pour gérer les erreurs, les développeurs sont tentés de retarder la création de la gestion des erreurs dans leurs applications. Néanmoins, sans gestion des erreurs, une application risque de s’interrompre ou de poser des problèmes à l’utilisateur si elle ne fonctionne pas comme prévu. ActionScript 2.0 possède une classe Error qui vous permet de créer une logique dans des fonctions personnalisées afin de renvoyer une exception avec un message spécifique. Etant donné que la gestion des erreurs est cruciale pour rendre une application conviviale, ActionScript 3.0 inclut une architecture étendue pour intercepter les erreurs. Remarque : bien que le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash passe en revue les exceptions renvoyées par de nombreuses méthodes, il ne contient pas nécessairement toutes les exceptions associées à chaque méthode. une méthode risque de renvoyer une exception due à une erreur de syntaxe ou d’autres problèmes qui ne sont pas signalés explicitement dans la description de la méthode, même si cette dernière répertorie certaines exceptions renvoyées.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures ActionScript 3.0 comprend de nombreux outils permettant de gérer les erreurs, notamment :
MemoryError), à des erreurs de codage (comme une condition ArgumentError), à des erreurs de réseau et de communication (comme une condition URIError), ou d’autres situations. Pour plus d’informations sur chaque classe, voir « Comparaison des classes Error » à la page 68.
Ces erreurs permettent de gérer les exceptions de manière plus efficace au moment où elles se produisent, puis de réagir à chaque exception.
« Utilisation des instructions try..catch..finally » à la page 59.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Tant que l’application ne rencontre pas de condition problématique, vous pouvez continuer à l’exécuter sans créer de logique de gestion des erreurs dans le code. En revanche, si vous ne gérez pas d’erreurs de façon active et que votre application rencontre un problème, vos utilisateurs ignoreront toujours la raison de son échec. Vous pouvez aborder la gestion des erreurs de diverses façons dans votre application. La liste suivante résume les trois principales options de gestion des erreurs :
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Adobe propose aux développeurs des éditions spéciales des moteurs d’exécution Flash, destinées à les aider à exécuter des opérations de débogage. Vous obtenez une copie de la version de débogage de Flash Player lorsque vous installez Adobe Flash Professional ou Adobe Flash Builder. Vous disposez également d’un utilitaire de débogage des applications Adobe AIR, appelé ADL, lorsque vous installez l’un de ces outils ou dans le cadre de l’installation du SDK d’Adobe AIR.
EOFError générique), le numéro de l’erreur et un message d’erreur sous une forme lisible par une personne. Les versions mises sur le marché indiquent uniquement le type d’erreur et son numéro. Considérons par exemple le code qui suit : try { tf.text = myByteArray.readBoolean(); } catch (error:EOFError) { tf.text = error.toString(); événements personnalisés portant le nom « allComplete ». Vous risquez sinon de rencontrer un comportement imprévisible lors du débogage. Ce type de version ne comprend pas de chaîne de message d’erreur, afin de réduire au minimum la taille et les ressources requises. Vous pouvez consulter le numéro d’erreur dans la documentation (annexes du manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash) pour l’associer à un message d’erreur. Vous pouvez également reproduire l’erreur dans les versions de débogage de Flash Player et AIR pour visualiser le message entier.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La gestion des erreurs la plus courante est la logique de gestion des erreurs synchrones, qui consiste à insérer des instructions dans votre code pour intercepter les erreurs synchrones lors de l’exécution d’une application. Ce type de gestion des erreurs permet à votre application de repérer des erreurs d’exécution et de les résoudre lorsque des fonctions échouent. La logique d’interception d’une erreur synchrone fait appel aux instructions try..catch..finally, qui tentent littéralement une opération, interceptent toute réponse à l’erreur émanant du moteur d’exécution Flash, puis exécutent une autre opération pour gérer l’opération qui a échoué.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lorsque vous manipulez des erreurs d’exécution synchrones, utilisez les instructions try..catch..finally pour intercepter les erreurs. Lorsqu’une erreur d’exécution se produit, le moteur d’exécution Flash renvoie une exception, ce qui signifie qu’il suspend l’exécution normale et crée un objet spécial de type Error. L’objet Error est ensuite renvoyé au premier bloc catch disponible.
à cette instruction try sont exécutées. L’instruction finally regroupe les instructions exécutées, qu’une erreur se produise ou non dans le bloc try. S’il ne se produit pas d’erreur, les instructions du bloc finally sont exécutées au terme de l’exécution des instructions du bloc try. S’il se produit une erreur, l’instruction catch appropriée est exécutée en premier lieu, suivie des instructions du bloc finally. Le code suivant illustre la syntaxe d’utilisation des instructions try..catch..finally : try { // some code that could throw an error } catch (err:Error) Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les moteurs d’exécution Flash renvoient des exceptions s’ils rencontrent des erreurs lors de l’exécution de votre application. En outre, vous pouvez renvoyer des exceptions de façon explicite à l’aide de l’instruction throw. Si tel est le cas, Adobe vous conseille de renvoyer des occurrences de la classe Error ou de ses sous-classes. Le code suivant illustre une instruction throw qui renvoie une occurrence de la classe Error, MyErr, et appelle une fonction, myFunction() en réponse au renvoi de l’erreur :
Remarque : dans le langage de programmation Java, chaque fonction qui peut renvoyer une exception doit le déclarer en répertoriant les classes d’exception qu’elle peut renvoyer dans une clause throws associée à la déclaration de la fonction. ActionScript ne requiert pas que vous déclariez les exceptions renvoyées par une fonction.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’un des avantages majeurs du nouveau modèle d’événement d’erreur et d’exception consiste à permettre d’informer les utilisateurs du moment où une action échoue et de la raison de cet échec. Votre rôle consiste à écrire le code pour afficher le message et à offrir des options en réponse. Le code suivant illustre une instruction try..catch simple permettant d’afficher l’erreur dans un champ de texte :
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lorsque vous créez une application, vous êtes parfois amené à renvoyer une erreur si vous ne parvenez pas à la gérer correctement. Par exemple, le code suivant illustre un bloc try..catch imbriqué, qui renvoie une erreur ApplicationError personnalisée si le bloc catch imbriqué n’est pas capable de gérer l’erreur :
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous pouvez étendre l’une des classes Error standard pour créer vos classes d’erreur spécialisées dans ActionScript. Vous pouvez créer vos classes d’erreur pour les motifs suivants :
Outre les erreurs interceptées par un moteur d’exécution de Flash, vous pouvez par exemple gérer différemment les erreurs renvoyées par votre propre code. Vous pouvez créer une sous-classe de la classe Error pour suivre le nouveau type de données d’erreur dans les blocs try..catch.
Par exemple, vous pouvez créer une méthode toString() qui formate vos messages d’erreur d’une certaine façon. Vous pouvez également définir une méthode lookupErrorString() qui prend un code d’erreur et récupère le message adéquat en fonction du langage que l’utilisateur préfère. Une classe d’erreur spécialisée doit étendre la classe Error d’ActionScript de base. Voici un exemple de classe AppError spécialisée qui étend la classe Error :
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’une des améliorations majeures apportées à la gestion des erreurs dans ActionScript 3.0 est la prise en charge de la gestion des événements d’erreur pour répondre à des erreurs asynchrones lors de l’exécution d’une application. (Pour obtenir une définition des erreurs asynchrones, voir « Types d’erreurs » à la page 55). Vous pouvez créer des écouteurs d’événement et des gestionnaires d’événements pour répondre aux événements d’erreurs. De nombreuses classes distribuent des événements d’erreurs de la même façon que d’autres événements. Par exemple, une occurrence de la classe XMLSocket distribue normalement trois types d’événements :Event.CLOSE, Event.CONNECT et DataEvent.DATA. Néanmoins, lorsqu’un problème se produit, la classe XMLSocket peut distribuer IOErrorEvent.IOError ou SecurityErrorEvent.SECURITY_ERROR. Pour plus d’informations sur les écouteurs et les gestionnaires d’événement, voir « Gestion des événements » à la page 129. Les événements d’erreurs peuvent être classés en deux catégories :
La classe flash.events.ErrorEvent contient les propriétés et les méthodes permettant de gérer les erreurs d’exécution liées à des opérations de réseau et de communication dans une application en cours d’exécution. Les classes AsyncErrorEvent, IOErrorEvent et SecurityErrorEvent étendent la classe ErrorEvent. Si vous utilisez la version de débogage d’un moteur d’exécution de Flash, une boîte de dialogue vous informe, lors de l’exécution, de la présence d’événements d’erreurs sans fonctions d’écouteur rencontrés par le lecteur.
La classe ErrorEvent et ses sous-classes contiennent des types d’erreurs destinés à gérer les erreurs distribuées par les moteurs d’exécution Flash lorsqu’ils tentent de lire ou d’écrire des données. L’exemple suivant utilise à la fois une instruction try..catch et des gestionnaires d’événement d’erreur pour afficher toute erreur détectée lors de la tentative de lecture d’un fichier local. Vous pouvez ajouter un code de gestion plus élaboré pour proposer des options à l’utilisateur ou gérer l’erreur automatiquement aux endroits indiqués par le commentaire « your error-handling code here » : package { import import import import import import import import import
L’exemple suivant utilise une fonction netStatusHandler() pour tester la valeur de la propriété level. Si la propriété level indique qu’une erreur a été rencontrée, le code suit le message « Video stream failed ». package { import import import import import import
Error dans votre propre code. Il existe deux types principaux de classes Error dans ActionScript 3.0 : les classes Error de base d’ActionScript et les classes Error du package flash.error. Le package flash.error contient des classes supplémentaires permettant le débogage et le développement d’applications ActionScript 3.0.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Parmi les classes Error de base figurent les classes Error, ArgumentError, EvalError, RangeError, ReferenceError, SecurityError, SyntaxError, TypeError, URIError et VerifyError. Chacune de ces classes se trouve dans l’espace de noms de niveau supérieur.
Function ou si le code utilisateur appelle la fonction entraîne le renvoi d’une erreur. eval(). Les versions précédentes de Flash Player utilisaient la fonction eval() pour accéder à des variables, des propriétés, des objets ou des clips par nom.
également être renvoyée si vous tentez d’ajouter un objet d’affichage à une profondeur non valide.
Les versions du compilateur ActionScript antérieures à ActionScript 3.0 ne renvoyaient pas d’erreur lorsque vous tentiez d’accéder à une propriété non définie. ActionScript 3.0 renvoie toutefois l’exception ReferenceError dans ce cas de figure.
Cependant, si vous n’avez pas l’habitude d’initialiser les variables, ce nouveau comportement d’ActionScript requiert de vous quelques changements lorsque vous écrivez du code.
Une exception URIError peut être renvoyée dans les cas suivants :
SWF incorrect ou altéré est détecté.
SWF parent peut intercepter une exception VerifyError générée par le fichier SWF chargé.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le package flash.error contient des classes Error considérées comme parties intégrantes de l’API des moteurs d’exécution de Flash. A l’encontre des classes Error décrites, le package flash.error communique les événements d’erreurs propres aux moteurs d’exécution de Flash (tel Flash Player ou Adobe AIR).
IDataInput est appelée et que les données sont insuffisantes pour répondre à la requête de lecture.
• Une classe de base, telle que actuelle. DisplayObjectContainer, propose plus de fonctionnalités qu’une scène ne peut prendre en charge. Par exemple, si vous tentez d’obtenir ou de définir un masque sur la scène (à l’aide de stage.mask), le moteur d’exécution de Flash renvoie une exception IllegalOperationError accompagnée du message « La classe Stage n’implémente ni cette propriété, ni cette méthode ».
à allouer la mémoire requise pour une opération. Par conséquent, sur un système de bureau, cette exception est peu fréquente, à moins qu’une requête d’allocation ne soit extrêmement importante (par exemple, une requête de 3 milliards d’octets est impossible, car un programme Microsoft® Windows® de 32 bits peut accéder à 2 Go d’espace d’adressage uniquement).
Au chargement de l’application, la méthode initApp() est appelée dans les applications Flex ou le code du scénario (autre qu’une fonction) est exécuté dans les applications Flash Professional. Ce code définit un exemple de paquet XML que la classe Validator vérifiera. Le code suivant est exécuté : employeeXML = <employee id="12345"> <firstName>John</firstName> <lastName>Doe</lastName> (le nœud ssn dans le paquet XML). S’il n’y a pas exactement un nœud ssn, une erreur FatalError est renvoyée. Vous pouvez ajouter des vérifications supplémentaires à la méthode validateEmployeeXML() afin de vérifier, par exemple, que le nœud ssn contient un numéro valide, ou que l’employé possède au moins un numéro de téléphone et une adresse électronique, et que ces deux valeurs sont valides. Vous pouvez également modifier le XML de façon à ce que chaque employé ait un ID unique et spécifie l’ID de son responsable.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe ApplicationError sert de classe de base aux classes FatalError et WarningError. Elle étend la classe Error et définit ses propres propriétés et méthodes personnalisées, y compris un ID d’erreur, la gravité et un objet XML contenant les codes d’erreur personnalisés et les messages. Cette classe définit également deux constantes statiques utilisées pour définir la gravité de chaque type d’erreur. La méthode du constructeur de la classe ApplicationError est la suivante : public function ApplicationError() { messages = <errors> <error code="9000"> FatalError, getTitle() et toString(). La première méthode, le constructeur FatalError, prend un seul argument entier, errorID, et définit la gravité de l’erreur à l’aide des valeurs de constante statiques définies dans la classe ApplicationError. Elle obtient le message de l’erreur spécifique en appelant la méthode getMessageText() dans la classe ApplicationError. Le constructeur FatalError se présente comme suit : public function FatalError(errorID:int) { id = errorID; severity = ApplicationError.FATAL; message = getMessageText(errorID); }
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe WarningError étend la classe ApplicationError et est presque identique à la classe FatalError, à l’exception de quelques changements de chaîne mineurs. Elle définit la gravité de l’erreur sur ApplicationError.WARNING au lieu de ApplicationError.FATAL, comme indiqué dans le code suivant : public function WarningError(errorID:int) { id = errorID; severity = ApplicationError.WARNING; message = super.getMessageText(errorID); }
Les rubriques suivantes sont consacrées à la syntaxe de base de construction d’expressions régulières. Néanmoins, les expressions régulières peuvent être très complexes et comporter de nombreuses nuances. Vous pouvez vous documenter sur les expressions régulières sur le Web et dans les librairies. Différents environnements de programmation implémentent des expressions régulières de différentes façons. ActionScript 3.0 implémente des expressions régulières comme défini dans la version 3 de la spécification du langage ECMAScript (ECMA-262).
A, B et C, dans l’ordre : /ABC/
Les modèles d’expression régulière peuvent également être complexes et parfois sembler obscures, comme l’expression suivante pour établir une correspondance avec une adresse électronique valide : /([0-9a-zA-Z]+[-._+&])*[0-9a-zA-Z]+@([-0-9a-zA-Z]+[.])+[a-zA-Z]{2,6}/
Utilisation d’expressions régulières
La classe RegExp comprend les méthodes suivantes : test() et exec(). Pour plus d’informations, voir « Méthodes d’utilisation d’expressions régulières avec des chaînes » à la page 93. Concepts importants et terminologie La liste de référence suivante contient des termes importants relatifs à la fonctionnalité étudiée. Caractère d’échappement Caractère indiquant que le caractère qui suit doit être considéré comme un caractère de remplacement plutôt que comme un caractère littéral. Dans une syntaxe d’expression régulière, la barre oblique inverse (\) est le caractère d’échappement. Par conséquent, une barre oblique inverse suivie d’un autre caractère est un code spécial plutôt que le caractère à proprement parler. Indicateur Caractère qui spécifie une option associée au mode d’utilisation du modèle d’expression régulière (respect de la casse, par exemple). Caractère de remplacement Caractère qui a une signification spéciale dans un modèle d’expression régulière et qui ne représente pas littéralement ce caractère dans le modèle. Quantificateur Caractères indiquant le nombre de répétitions d’une partie du modèle. Par exemple, un quantificateur peut être utilisé pour indiquer qu’un code postal américain doit contenir cinq ou neuf chiffres. Expression régulière Instruction de programme définissant un modèle de caractères qui permet de confirmer si d’autres chaînes correspondent à ce modèle ou de remplacer des sections d’une chaîne.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Cette section décrit tous les éléments de la syntaxe d’expression régulière d’ActionScript. Comme vous pourrez le constater, les expressions régulières peuvent être très complexes et comporter de nombreuses nuances. Vous pouvez vous documenter sur les expressions régulières sur le Web et dans les librairies. Différents environnements de programmation implémentent des expressions régulières de différentes façons. ActionScript 3.0 implémente des expressions régulières comme défini dans la version 3 de la spécification du langage ECMAScript (ECMA-262). Généralement, vous utilisez des expressions régulières qui correspondent à des modèles plus compliqués qu’une simple chaîne de caractères. Par exemple, l’expression régulière suivante définit le modèle comportant les lettres A, B et C, dans l’ordre, suivies par un chiffre : /ABC\d/
L’expression régulière suivante définit le modèle des lettres ABC suivies par des chiffres (remarquez l’astérisque) : /ABC\d*/
Vous pouvez utiliser des expressions régulières à l’aide des méthodes suivantes de la classe String : match(), replace() et search(). 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.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Il existe deux façons de créer une occurrence d’expression régulière. L’une des méthodes consiste à utiliser des barres obliques (/) pour délimiter l’expression régulière, et l’autre consiste à utiliser le constructeur new. Par exemple, les expressions régulières suivantes sont équivalentes : var pattern1:RegExp = /bob/i; var pattern2:RegExp = new RegExp("bob", "i");
Lorsque vous utilisez le constructeur new, vous utilisez deux chaînes pour définir l’expression régulière. La première chaîne définit le modèle, et la seconde les indicateurs, comme dans l’exemple suivant : var pattern2:RegExp = new RegExp("bob", "i");
La section qui suit décrit la syntaxe servant à définir des modèles d’expression régulière. Pour plus d’informations, voir « Indicateurs et propriétés » à la page 89.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’expression régulière la plus simple est celle qui correspond à une séquence de caractères, comme dans l’exemple suivant : var pattern:RegExp = /hello/;
^ $ \ . * + ? ( ) [ ] { } |
B (le caractère de remplacement astérisque indique cette répétition), suivie par la lettre C : /AB*C/
Une métaséquence est constituée de plusieurs caractères. Les sections suivantes fournissent des détails sur l’utilisation des caractères de remplacement et des métaséquences. A propos des caractères de remplacement Le tableau suivant répertorie les caractères de remplacement que vous pouvez utiliser dans des expressions régulières :
Pour plus d’informations, voir « Indicateurs et propriétés » à la page 89.
Spécifie une classe de caractère qui définit des correspondances possibles pour un seul caractère : /[aeiou]/ correspond à l’un des caractères spécifiés.
/[A-Z0-9]/ correspond aux lettres majuscules A à Z ou aux chiffres 0 à 9.
/[+\-]\d+/ correspond à + ou à - avant un ou plusieurs chiffres.
/[$]/£ correspond à $ou à £.
| (opérateur de transfert de
/abc|xyz/ correspond à abc ou à xyz.
Vous utilisez des classes de caractère pour spécifier une liste de caractères devant correspondre à une position dans l’expression régulière. Vous définissez des classes de caractère avec des crochets ( [ et ] ). Par exemple, l’expression régulière suivante définit une classe de caractère qui remplace bag, beg, big, bog ou bug : /b[aeiou]g/
Caractère de remplacement
Plages de caractères dans des classes de caractère Utilisez le trait d’union pour spécifier une plage de caractères telle que A-Z, a-z, ou 0-9. Ces caractères doivent constituer une plage valide dans le jeu de caractères. Par exemple, la classe de caractère suivante correspond à un caractère compris dans la plage a-z ou un chiffre : /[a-z0-9]/
\\x à un symbole (le caret, notamment) : /[!.,#+*%$&^]/
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous utilisez des quantificateurs pour spécifier des répétitions de caractères ou de séquences dans des modèles, comme suit : Caractère de remplacement de quantificateur
Par exemple, le quantificateur suivant correspond à des chaînes du type word et word-word-word : /\w+(-\w+)*/
<p>Paragraph 1</p> <p>Paragraph 2</p>
// output: <p>Test //
/1|3|5|7|9/ /[13579]/ Un groupe est une sous-section d’un modèle. Vous pouvez utiliser des groupes pour effectuer les opérations suivantes :
• Délimiter des sous-modèles à appliquer avec la permutation (à l’aide du caractère |) • Capturer des correspondances de sous-chaîne (par exemple, en utilisant \1 dans une expression régulière pour établir une correspondance avec un groupe mis en correspondance précédemment, ou en utilisant $1 de la même façon dans la méthode replace() de la classe String) Les sections suivantes fournissent des détails sur ces utilisations de groupes. Utilisation de groupes avec des quantificateurs Si vous n’utilisez pas de groupe, un quantificateur s’applique au caractère ou à la classe de caractère qui le précède, comme indiqué ci-dessous : var pattern:RegExp = /ab*/ ; // matches the character a followed by // zero or more occurrences of the character b pattern = /a\d+/; // matches the character a followed by Vous pouvez utiliser des groupes pour définir le groupe de caractères auquel vous souhaitez appliquer un permutateur (|), comme suit :
De même, dans la méthode replace() de la classe String, vous pouvez utiliser $1–$99 pour insérer des correspondances de chaîne de groupe capturé dans la chaîne de remplacement : var pattern:RegExp = /Hi, (\w+)\./; var str:String = "Hi, Bob."; trace(str.replace(pattern, "$1, hello.")); // output: Bob, hello.
// bob@example.com,bob,example,com Un groupe non capturé est utilisé pour le regroupement uniquement ; il n’est pas collecté et il ne correspond pas à des backreferences numérotées. Utilisez (?: et ) pour définir des groupes non capturés, comme suit : var pattern = /(?:com|org|net);
// bob@example.com,bob,example,com //noncapturing: var pattern:RegExp = /(\w+)@(\w+).(?:com|org)/; var str:String = "bob@example.com"; trace(pattern.exec(str)); Utilisez (?= et ) pour définir un groupe d’anticipation négatif, qui indique que le sous-modèle dans le groupe ne doit pas établir une correspondance à la position. Exemple : var pattern:RegExp = /sh(?!e)(\w*)/i; var str:String = "She sells seashells by the seashore"; trace(pattern.exec(str)); // shore,ore Lorsque vous utilisez la méthode exec(), un groupe nommé de correspondance est ajouté comme propriété du tableau result : var myPattern:RegExp = /([a-z]+)(?P<digits>\d+)[a-z]+/; var str:String = "a123bcd"; var result:Array = myPattern.exec(str); trace(result.digits); // 123
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le tableau suivant répertorie les cinq indicateurs que vous pouvez définir pour des expressions régulières. Vous pouvez accéder à chaque indicateur en tant que propriété de l’objet d’expression régulière.
Si l’indicateur m (multiline) n’est pas défini, le ^ correspond au début de la chaîne et le $ à sa fin. Si l’indicateur m est défini, ces caractères correspondent au début d’une ligne et à la fin d’une ligne, respectivement. Considérez la chaîne suivante, qui inclut un caractère de nouvelle ligne : var str:String = "Test\n"; str += "Multiline"; trace(str.match(/^\w*/g)); // Match a word at the beginning of the string.
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 :
Utilisation d’expressions régulières
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
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 :
• 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
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
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(); }
La méthode parseBold() recherche un modèle de texte Wiki en gras ('''foo''', par exemple) et le transforme en son équivalent HTML (<b>foo</b>, par exemple), comme suit : private function parseBold(input:String):String { var pattern:RegExp = /'''(.*?)'''/g; return input.replace(pattern, "<b>$1</b>"); }
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, "<i>$1</i>"); } 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). Conversion de modèles Wiki de paragraphe La méthode linesToParagraphs() convertit chaque ligne dans la chaîne Wiki d’entrée en une balise de paragraphe HTML <p>. 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, "");
(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).
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 (.).
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 <a>. 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.
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);
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 :
• 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 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.
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 : <song> <title>What you know?</title> <artist>Steve and the flubberblubs</artist> 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 : <song tracknumber="1" length="4:05"> <title>What do you know?</title> <artist>Steve and the flubberblubs</artist> 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 :
• 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 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.
Les méthodes, propriétés et opérateurs des classes E4X sont conçus avec les objectifs suivants :
• Cohérence : les méthodes et le raisonnement E4X sont cohérents avec eux-mêmes et avec d’autres parties d’ActionScript.
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 = <order> <item id='1'> <menuName>burger</menuName> Dernière mise à jour le 27/4/2013
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 nœuds 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 nœud de texte. Par exemple, l’objet XML suivant contient un contenu complexe, y compris un commentaire et une instruction de traitement :
• Les propriétés prettyIndentet prettyPrinting servent à formater le texte renvoyé par les méthodes toString() et toXMLString() de la classe XML.
Les méthodes suivantes vous permettent d’utiliser la structure hiérarchique des objets XML :
Les opérateurs et les méthodes des objets XML et XMLList permettent de parcourir aisément la structure des données XML. Utilisez l’opérateur point (.) et l’opérateur d’accesseur descendant (..) pour accéder aux propriétés enfant d’un objet XML. Considérez l’objet XML suivant : var myXML:XML = <order> <book ISBN="0942407296"> Accès aux nœuds enfant et parent Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La méthode parent() renvoie le parent d’un objet XML. Vous pouvez utiliser les valeurs d’index ordinales d’une liste enfant pour accéder à des objets enfant spécifiques. Par exemple, considérez un objet XML myXML ayant deux propriétés enfant appelées book. Chaque propriété enfant appelée book possède un numéro d’index qui lui est associé : myXML.book[0] myXML.book[1]
Utilisez le symbole @ (l’opérateur identifiant d’attribut) pour accéder aux attributs dans un objet XML ou XMLList, comme indiqué dans le code suivant : var employee:XML = <employee id="6401" code="233"> <lastName>Wu</lastName> <firstName>Erin</firstName> Vous pouvez utiliser les opérateurs parenthèses— ( et ) —pour filtrer des éléments avec un nom d’élément spécifique ou une valeur d’attribut. Considérez l’objet XML suivant : var x:XML = <employeeList> <employee id="347"> <lastName>Zmed</lastName> ActionScript 3.0 propose les instructions for..in et for each..in pour permettre les itérations dans les objets XMLList. Par exemple, considérez l’objet XML suivant, myXML, et l’objet XMLList, myXML.item. L’objet XMLList, myXML.item, est constitué de deux nœuds item de l’objet XML.
SOAP, vous déclarez l’espace de noms dans la balise de début de l’XML : var message:XML = <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <soap:Body xmlns:w="http://www.test.com/weather/"> <w:getWeatherResponse> Dernière mise à jour le 27/4/2013
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.
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 = <order> <item id='1' quantity='2'> <menuName>burger</menuName> 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 :
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(""); }
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();
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).
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):*
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
évalue chaque nom de propriété et renvoie l’encodage souhaité de sa valeur.
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 :
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 :
• Date • 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()
é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"; }
Dernière mise à jour le 27/4/2013
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é.
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):*
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; }); JSON en objet ActionScript utilisable. L’argument reviver est une fonction qui prend deux paramètres et renvoie tout type : function (k,v):*
ActionScript exportés tout en gardant intacts les objets d’origine.
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.
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++; é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.
Package flash.events 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.
Gestion des événements
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); 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
Phase de propagation Partie du flux d’événements dans laquelle un événement est propagé jusqu’aux objets
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
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
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.
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.
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 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.
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.
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é.
é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 :
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 nœud cible. Selon la définition de la spécification d’événements DOM, le nœud cible est le nœud 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 nœuds rencontrés lors du cheminement du parent du nœud cible jusqu’à la scène.
Dans cet exemple, la phase de capture comprend Scène et Nœud parent pendant le trajet descendant initial. La phase cible comprend le temps passé au nœud Nœud enfant1. La phase de propagation comprend les nœuds Nœud parent et Scène, qui se trouvent sur le chemin du retour vers le nœud 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 nœud 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.
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.
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 :
• 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.
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);
{ public class Event { é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é 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 nœud 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 :
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 nœud 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.
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 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é
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 nœud actuel sont autorisés ou non à 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.
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.
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.
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é.
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.
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 :
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.
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); Dernière mise à jour le 27/4/2013
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; } 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.
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.
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 :
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.
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 :
• Notification d’un événement aux écouteurs • Créer un type d’événement personnalisé
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.
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.
Gestion des événements
/** 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 :
(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.
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);
é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.
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 :
Dernière mise à jour le 27/4/2013
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() :
Utilisation de domaines d’application
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.
Utilisation A Partitionnez le fichier SWF enfant en créant un enfant du domaine du système. Dans le schéma, le
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);
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);
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.
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.
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.
é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.
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 : 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.
Liste d’affichage Hiérarchie des objets d’affichage rendus sous forme de contenu visible à l’écran par Flash Player
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
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
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).
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. 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 :
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.
Pour plus d’informations, voir « Utilisation de l’API de dessin » à la page 230.
« over » et « hit test » (zone qui réagit aux événements souris et clavier).
Programmation de l’affichage
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 :
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.
DisplayObjectContainer. Pour plus d’informations, voir « Utilisation de conteneurs d’objets d’affichage » à la page 165.
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.
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.
« Présentation à accélération matérielle par le biais de la classe StageVideo » à la page 528.
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.ProLoaderInfo : équivalente à flash.display.LoaderInfo
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 :
• 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
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.
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.
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.
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.
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.
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); } Dernière mise à jour le 27/4/2013
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.
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);
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;
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) :
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.
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
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 :
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.
DisplayObjectContainer) :
{ 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) La méthode remplacée demande dans ce cas que l’objet enfant ajouté soit de type mx.core.UIComponent.
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.
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.
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.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.
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.
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; }
Modifier la propriété scaleMode entrave le fonctionnement des mécanismes de mise en forme automatique utilisés dans ces types de fenêtres.
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 quitter le mode plein écran, définissez la propriété displayState sur StageDisplayState.NORMAL. stage.displayState = StageDisplayState.NORMAL;
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 :
Dans Flex, assurez-vous que le modèle HTML inclut les balises <object> et <embed> qui prennent en charge le plein écran. Si vous utilisez JavaScript dans une page Web pour générer les balises d’intégration de SWF, vous devez modifier le code JavaScript pour ajouter la balise et l’attribut allowFullScreen param. Par exemple, si votre page HTML fait appel à la fonction AC_FL_RunContent() (utilisée par les pages HTML générées par Flash Professional et Flash Builder), vous devez ajouter le paramètre allowFullScreen à cet appel de fonction, comme suit : AC_FL_RunContent( ... 'allowFullScreen','true', Transparent sans fenêtre (transparent), la fenêtre plein écran est toujours opaque. Il existe également des restrictions liées à la sécurité lors de l’utilisation du mode plein écran avec Flash Player dans un navigateur. Ces restrictions sont décrites dans le chapitre « Sécurité » à la page 1085. Activation du mode interactif plein écran dans Flash Player 11.3 et les versions ultérieures Flash Player 11.3 et les versions ultérieures prennent en charge le mode interactif plein écran, qui permet une prise en charge totale de toutes les touches du clavier (à l’exception de la touche Echap, qui permet de quitter le mode interactif plein écran). Le mode interactif plein écran est utile pour les jeux (par exemple pour activer la fonction de dialogue en ligne dans un jeu multijoueurs ou les commandes du clavier WASD dans un jeu de tir subjectif.) Pour activer le mode interactif 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 allowFullScreenInteractive et à la valeur true, comme suit : <object> ... <param name="allowFullScreenInteractive" value="true" /> Si vous utilisez JavaScript dans une page Web pour générer les balises d’intégration de SWF, vous devez modifier le code JavaScript pour ajouter la balise et l’attribut allowFullScreenInteractive param. Par exemple, si votre page HTML fait appel à la fonction AC_FL_RunContent() (utilisée par les pages HTML générées par Flash Professional et Flash Builder), vous devez ajouter le paramètre allowFullScreenInteractive à cet appel de fonction, comme suit :
Les propriétés Stage.fullScreenHeight et Stage.fullScreenWidth renvoient la hauteur et la largeur de l’écran utilisé lors de l’activation du mode plein écran, lorsque le passage à cet état est immédiat. Ces valeurs risquent d’être incorrectes si l’utilisateur déplace le navigateur d’un écran à un autre après avoir récupéré ces valeurs, mais avant de passer au mode plein écran. Si l’utilisateur récupère ces valeurs dans le gestionnaire d’événement dans lequel il a défini la propriété Stage.displayState sur StageDisplayState.FULL_SCREEN, celles-ci sont correctes. Pour les utilisateurs qui utilisent plusieurs écrans, le contenu du fichier SWF s’étend pour n’occuper qu’un seul écran. Flash Player et AIR utilisent une mesure pour identifier le moniteur contenant la portion la plus élevée du fichier SWF et activent le mode plein écran sur celui-ci. Les propriétés fullScreenHeight et fullScreenWidth ne reflètent que la taille du moniteur utilisé en mode plein écran. Pour plus d’informations, voir Stage.fullScreenHeight et Stage.fullScreenWidth dans le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash. En mode plein écran, le comportement de mise à l’échelle de la scène est identique à celui du mode normal. Cette mise à l’échelle est contrôlée par la propriété scaleMode de la classe Stage. Si la propriété scaleMode est définie sur StageScaleMode.NO_SCALE, les propriétés stageWidth et stageHeight de la classe Stage sont modifiées pour répercuter la taille de la zone de l’écran occupée par le fichier SWF (soit, dans ce cas, l’écran entier). Dans un navigateur, le paramètre HTML correspondant contrôle le réglage. L’événement fullScreen de la classe Stage permet de détecter et répondre à l’activation ou à la désactivation du mode plein écran. Par exemple, il peut être nécessaire de repositionner, d’ajouter ou de supprimer des éléments lors d’un changement d’état du mode plein écran, comme illustré par cet exemple : import flash.events.FullScreenEvent; function fullScreenRedraw(event:FullScreenEvent):void { if (event.fullScreen) { // Remove input text fields. Lorsque Flash Player est exécuté dans un navigateur, l’ensemble du code ActionScript lié au clavier (événements de clavier et saisie de texte dans des occurrences de TextField, entre autres), est désactivé en mode plein écran. Les exceptions (c’est-à-dire les touches qui restent actives) sont les suivantes :
(Windows), Commande-W (Mac) et Alt-F4 Ces restrictions ne sont pas présentes pour le contenu SWF s’exécutant dans l’application Flash Player autonome ou dans AIR. AIR prend en charge un mode plein écran interactif qui permet la saisie clavier. Prise en charge de la souris en mode plein écran Par défaut, les événements de souris fonctionnent de la même façon en mode plein écran que dans un autre mode d’affichage. Néanmoins, le mode plein écran permet également de définir la propriété Stage.mouseLock en vue de verrouiller la souris. Le verrouillage de la souris désactive le curseur et permet de déplacer la souris sans aucune limite. Remarque : vous pouvez verrouiller la souris uniquement sur des applications de bureau en mode plein écran. Le verrouillage de la souris sur des applications dans un autre mode d’affichage ou sur des applications mobiles renvoie une exception. Le verrouillage de la souris est automatiquement désactivé et le curseur de la souris est à nouveau visible lorsque :
Ctrl-W (Windows), Cmd-W (Mac) ou Alt-F4 (Windows) ;
• une interface de paramétrage est visible, notamment une boîte de dialogue de confidentialité ; • une boîte de dialogue native s’affiche, notamment une boîte de dialogue de téléchargement d’un fichier. Les événements associés au mouvement de la souris, tels que l’événement mouseMove, font appel à la classe MouseEvent pour représenter l’objet de l’événement. Lorsque le verrouillage de la souris est désactivé, utilisez les propriétés MouseEvent.localX et MouseEvent.localY pour déterminer l’emplacement de la souris. Lorsque le verrouillage de la souris est activé, utilisez les propriétés MouseEvent.movementX et MouseEvent.movementY pour déterminer l’emplacement de la souris. Les propriétés movementX et movementY contiennent les changements de position de la souris depuis le dernier événement plutôt que les coordonnées absolues de l’emplacement de la souris. Mise à l’échelle matérielle en mode plein écran La propriété fullScreenSourceRect de la classe Stage permet d’utiliser Flash Player ou AIR pour mettre à l’échelle une zone déterminée de la scène en mode plein écran. Dans Flash Player et AIR, la mise à l’échelle matérielle, si elle est disponible, s’effectue à l’aide de la carte graphique et de la carte vidéo de l’ordinateur, et permet généralement d’afficher le contenu plus rapidement que la mise à l’échelle logicielle. Pour tirer parti de la mise à l’échelle matérielle, définissez l’ensemble ou une partie de la scène sur le mode plein écran. Le code suivant ActionScript 3.0 définit l’ensemble de la scène en mode plein écran : import flash.geom.*; { stage.fullScreenSourceRect = new Rectangle(0,0,320,240); stage.displayState = StageDisplayState.FULL_SCREEN; }
Player et AIR redimensionnent la zone spécifiée. La taille réelle de la scène en pixels dans ActionScript ne change pas. Flash Player et AIR imposent une taille limite au rectangle en fonction de la taille du message standard « Appuyez sur la touche Echap pour quitter le mode plein écran ». Cette limite est généralement d’environ 260 sur 30 pixels, mais peut varier en fonction de la plate-forme et de la version de Flash Player. La propriété fullScreenSourceRect ne peut être définie que lorsque Flash Player ou AIR ne sont pas en mode plein écran. Pour utiliser correctement cette propriété, vous devez tout d’abord la définir, puis définir la propriété displayState sur le mode plein écran. Pour activer la mise à l’échelle, définissez la propriété fullScreenSourceRect sur un objet rectangle. stage.fullScreenSourceRect = new Rectangle(0,0,320,240);
Modes Fenêtre direct et composition GPU Flash Player 10 propose deux modes de fenêtre, direct et composition GPU, que vous pouvez activer dans les paramètres de publication de l’outil de programmation Flash. Ces modes ne sont pas pris en charge par AIR. Pour tirer parti de ces modes, vous devez activer l’accélération matérielle pour Flash Player. Le mode direct utilise le chemin le plus rapide et le plus direct pour placer des graphismes sur l’écran, ce qui est pratique pour la lecture vidéo. La composition GPU utilise l’unité de traitement graphique sur la carte vidéo pour accélérer la composition. La composition vidéo consiste à créer des images multi-couches pour aboutir à une seule image vidéo. Lorsque la composition est accélérée par la GPU, les performances de la conversion YUV, la correction des couleurs, la rotation, le redimensionnement et le fondu sont nettement améliorés. La conversion YUV se réfère à la conversion des couleurs de signaux analogiques composites, qui sont utilisées pour la transmission, au modèle de couleurs RVB (rouge-vertbleu) que les caméras vidéo et les écrans utilisent. Le recours à la GPU pour accélérer la composition réduit la demande en mémoire et en puissance de calcul qui affectera les performances de l’unité centrale. Il en résulte une lecture vidéo plus régulière en définition standard. Soyez vigilant lorsque vous implémentez ces modes Fenêtre. Fenêtre L’utilisation de la composition GPU peut s’avérer coûteuse en mémoire et en ressources de l’unité centrale. Si certaines opérations (comme les modes fondu, le filtrage, l’écrêtage ou le masquage) ne peuvent pas être exécutées dans la GPU, c’est le logiciel qui s’en charge. Adobe vous recommande de vous limiter à un fichier SWF par page HTML lorsque vous utilisez ces modes. Il ne faudrait pas les utiliser pour des bandeaux. La Flash Test Movie facility ne fait pas appel à l’accélération matérielle mais vous pouvez l’utiliser par le biais de l’option Aperçu avant publication. Il est inutile de fixer une cadence supérieure à 60 (c’est la fréquence de régénération d’écran maximale) dans votre fichier SWF. Une cadence entre 50 et 55 débouche sur des images perdues, ce qui peut se produire de temps à autre pour des raisons diverses.
Vous pouvez activer les modes d’accélération direct et gpu pour chaque SWF par le biais de la boîte de dialogue Paramètres de publication de Flash, à l’aide du menu d’accélération matérielle sur l’onglet Flash. Si vous choisissez Aucun, le mode Fenêtre revient à défaut, transparent ou opaque, selon le paramètre du Mode Fenêtre de l’onglet HTML.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe DisplayObject hérite de la classe EventDispatcher. Cela signifie que chaque objet d’affichage peut être pleinement impliqué dans le modèle d’événement (décrit dans le chapitre « Gestion des événements » à la page 129). Chaque objet d’affichage peut utiliser sa méthode addEventListener() (héritée de la classe EventDispatcher) pour attendre un événement particulier, mais ceci uniquement si l’objet écouteur fait partie du flux d’événement de l’événement considéré. Lorsque Flash Player ou AIR distribue un objet événement, celui-ci effectue un aller-retour à partir de la scène via l’objet d’affichage où s’est produit l’événement. Par exemple, si un utilisateur clique sur un objet d’affichage appelé child1, Flash Player distribue un objet événement à partir de la scène via la hiérarchie de la liste d’affichage jusqu’à l’objet d’affichage child1. D’un point de vue conceptuel, le flux d’événement est divisé en trois phases, comme illustré par le diagramme suivant :
Lors de la gestion des événements liés aux objets d’affichage, il est important de ne pas oublier l’effet potentiel des objets écouteurs d’événement sur l’éventuelle suppression automatique des objets d’affichage de la mémoire (garbage collection) lorsqu’ils sont supprimés de la liste d’affichage. Si des objets d’un objet d’affichage sont enregistrés en tant qu’écouteurs d’événement, ce dernier n’est pas supprimé de la mémoire même s’il est supprimé de la liste d’affichage, car il continue à posséder des références à ces objets écouteur. Pour plus d’informations, voir « Gestion des écouteurs d’événement » à la page 143.
Plusieurs options étant disponibles, l’une des décisions importantes à prendre lors de l’utilisation d’objets d’affichage est le choix de l’objet à utiliser dans un but précis. Les directives suivantes vous aideront à choisir l’option appropriée. Ces suggestions sont valides que vous créiez une occurrence de classe ou que vous choisissiez une classe de base pour une classe en cours de création :
DisplayObject ou d’InteractiveObject, selon l’utilisation prévue :
• TextField, pour ajouter du texte. • Video, pour afficher une vidéo. • Shape, pour disposer d’une « toile » destinée au tracé d’un contenu à l’écran. En particulier si vous souhaitez créer une occurrence pour dessiner des formes à l’écran et qu’elle ne contient pas d’autres objets d’affichage, vous obtiendrez des performances nettement supérieures en utilisant Shape plutôt que Sprite ou MovieClip.
Loader. Son type de données variera selon la nature du contenu chargé, comme suit :
• Un fichier SWF chargé écrit dans ActionScript 3.0 est une occurrence de Sprite ou MovieClip (ou une occurrence d’une sous-classe de ces classes, comme indiqué par le créateur du contenu).
• Si vous avez besoin d’un objet qui sera le conteneur d’autres objets d’affichage (que vous ayez ou non l’intention de dessiner en ActionScript dans cet objet), choisissez l’une des sous-classes de DisplayObjectContainer :
• Si vous créez une classe qui sera associée à un symbole de clip de la bibliothèque de Flash, choisissez l’une des sousclasses de DisplayObjectContainer comme classe de base de votre future classe :
• Sprite, si le symbole de clip associé ne possède un contenu que sur la première image.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Quel que soit l’objet d’affichage utilisé, tous les éléments affichés à l’écran partagent diverses techniques de manipulations. Par exemple, ils peuvent tous être positionnés à l’écran, avancer ou reculer dans l’ordre d’empilement des objets d’affichage, mis à l’échelle, pivotés, et ainsi de suite. Dans la mesure où tous les objets d’affichage héritent ces fonctionnalités de leur classe de base commune (DisplayObject), lesdites fonctionnalités ont le même comportement pour une occurrence d’un objet TextField, Video, Shape ou tout autre objet d’affichage. Les sections suivantes passent en revue plusieurs de ces manipulations appliquées à tous les objets d’affichage.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La manipulation la plus fondamentale de tout objet d’affichage consiste à le positionner à l’écran. Pour définir la position d’un objet d’affichage, changez ses propriétés x et y. myShape.x = 17; myShape.y = 212;
(système de grille standard doté d’un axe horizontal x et d’un axe vertical y). L’origine du système de coordonnées (coordonnée 0,0 correspondant à l’intersection des axes x et y) figure dans le coin supérieur gauche de la scène. A partir de l’origine, les valeurs x sont positives vers la droite et négatives vers la gauche, tandis que, contrairement aux systèmes de graphes standard, les valeurs y sont positives vers le bas et négatives vers le haut. Par exemple, les lignes précédentes de code déplacent l’objet myShape vers la coordonnée x 17 (17 pixels sur la droite de l’origine) et la coordonnée y 212 (212 pixels sous l’origine). Par défaut, lorsqu’un objet d’affichage est créé dans ActionScript, les propriétés x et y sont toutes deux définies sur 0, plaçant ainsi l’objet dans le coin supérieur gauche de son contenu parent.
Il est important de se rappeler que les propriétés x et y se réfèrent toujours à la position de l’objet d’affichage par rapport aux coordonnées 0,0 des axes de son objet d’affichage parent. Ainsi, pour une occurrence de Shape (par exemple un cercle) contenue dans une occurrence de Sprite, mettre à zéro les propriétés x et y de l’objet Shape revient à placer le cercle dans le coin supérieur gauche de l’objet Sprite, qui n’est pas forcément le coin supérieur gauche de la scène. Pour positionner un objet par rapport aux coordonnées globales de la scène, utilisez la méthode globalToLocal() de tout objet d’affichage afin de convertir les coordonnées globales (scène) en coordonnées locales (conteneur de l’objet d’affichage), comme suit :
Remarque : Flash Player 11.3 et les versions ultérieures et AIR 3.3 et les versions ultérieures : vous pouvez également utiliser l’événement MouseEvent.RELEASE_OUTSIDE dans le cas d’un utilisateur qui relâche le bouton de la souris en dehors des limites du Sprite conteneur. La première technique, basée sur la méthode startDrag(), est plus simple, mais plus limitée. Lorsque l’utilisateur appuie sur le bouton de la souris, la méthode startDrag() de l’objet d’affichage à faire glisser est appelée. Lorsque l’utilisateur relâche le bouton de la souris, la méthode stopDrag() est appelée. Puisque la classe Sprite définit ces deux fonctions, l’objet déplacé doit être un Sprite ou l’une de ses sous-classes.
Dernière mise à jour le 27/4/2013
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Si la taille d’un objet d’affichage est trop élevée pour la zone où vous souhaitez l’afficher, vous disposez de la propriété scrollRect pour définir la zone visible de l’objet d’affichage. Par ailleurs, en modifiant la propriété scrollRect en réponse à une action de l’utilisateur, vous pouvez entraîner un défilement vers la gauche ou la droite ou vers le haut ou le bas. La propriété scrollRect est une occurrence de la classe Rectangle, qui combine les valeurs requises pour définir une zone rectangulaire en tant qu’objet unique. Pour définir initialement la zone visible de l’objet d’affichage, créez une occurrence de Rectangle et affectez-la à la propriété scrollRect de l’objet. Par la suite, pour obtenir un défilement horizontal ou vertical, il suffit de lire la propriété scrollRect dans une variable Rectangle séparée et de changer la propriété voulue (par exemple, modifier la propriété x de l’occurrence de Rectangle pour un défilement horizontal, ou sa propriété y pour un défilement vertical). Vous réaffectez ensuite cette occurrence de Rectangle à la propriété scrollRect pour avertir l’objet d’affichage du changement de valeur. Par exemple, le code suivant définit la zone visible d’un objet TextField nommé bigText dont la hauteur est trop importante pour les dimensions du fichier SWF. Lorsque l’utilisateur clique sur les deux boutons nommés up et down, les fonctions appelées entraînent le défilement vertical du contenu de l’objet TextField en modifiant la propriété y de l’occurrence de Rectangle scrollRect.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La taille d’un objet d’affichage peut être obtenue et modifiée de deux façons, en utilisant soit les propriétés de dimensions (width et height), soit les propriétés d’échelle (scaleX et scaleY). Chaque objet d’affichage possède une propriété width et une propriété height, qui sont initialement définies sur la taille de l’objet en pixels. Vous pouvez lire les valeurs de ces propriétés pour mesurer la taille de l’objet d’affichage. Vous pouvez également stipuler de nouvelles valeurs pour modifier la taille de l’objet, comme suit :
Remarque : les objets TextField ne respectent pas ce comportement de mise à l’échelle. Les champs de texte doivent se redimensionner automatiquement pour gérer le retour à la ligne automatique et les tailles de police. Leurs valeurs scaleX et scaleY sont donc réinitialisées à 1 au terme du redimensionnement. Toutefois, si vous ajustez la valeur scaleX ou scaleY d’un objet TextField, les valeurs de largeur et de hauteur sont modifiées en fonction des valeurs de mise à l’échelle que vous indiquez. Ces propriétés représentent la taille relative de l’objet d’affichage par rapport à sa taille d’origine. Les propriétés scaleX et scaleY utilisent des valeurs exprimées sous forme de fractions (décimales) pour représenter le pourcentage. Par exemple, si la propriété width d’un objet d’affichage a été réduite à la moitié de sa largeur originale, la propriété scaleX de cet objet prendra la valeur 0,5, soit 50 %. Si sa hauteur a doublé, sa propriété scaleY prendra la valeur 2, soit 200 %. // circle is a display object whose width and height are 150 pixels. // At original size, scaleX and scaleY are 1 (100%). trace(circle.scaleX); // output: 1 trace(circle.scaleY); // output: 1 // When you change the width and height properties, Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures En règle générale, lorsqu’un objet d’affichage est mis à l’échelle (s’il est étiré horizontalement, par exemple), la distorsion résultante est répartie équitablement dans l’objet, de sorte que chaque partie soit soumise à un étirement identique. Pour les graphiques et éléments de conception, cette technique correspond probablement au résultat escompté. Toutefois, il est parfois préférable de garder le contrôle sur les parties de l’objet qui seront étirées et celles qui ne le seront pas. Un exemple courant est celui d’un bouton représenté par un rectangle aux angles arrondis. Lors d’une mise à l’échelle normale, les angles du bouton sont étirés, entraînant ainsi la modification de leur rayon lorsque le bouton est redimensionné.
En ActionScript, il suffit de définir une valeur pour la propriété scale9Grid d’un objet d’affichage pour activer la mise à l’échelle à 9 découpes pour cet objet et définir la taille des rectangles de la grille. Vous utilisez une occurrence de la classe Rectangle en tant que valeur de la propriété scale9Grid, comme suit :
La zone figurant dans la région définie par l’occurrence de Rectangle représente le rectangle central de la grille Echelle9. Les autres rectangles sont calculés par Flash Player et AIR en prolongeant les côtés de l’occurrence de Rectangle, comme indiqué :
L’objet d’affichage est essentiellement une surface, c’est-à-dire une version bitmap des données vectorielles de l’occurrence, données non destinées à être considérablement modifiées tout au long de la vie de votre fichier SWF. Ainsi, les occurrences pour lesquelles la mise en cache est activée ne sont pas continuellement redessinées pendant la lecture du fichier SWF, et le rendu de ce dernier est plus rapide. Remarque : vous pouvez mettre à jour les données vectorielles au moment de la recréation de la surface. Ainsi, les données vectorielles mises en cache dans la surface ne doivent pas nécessairement être les mêmes pour l’ensemble du fichier SWF.
à la page 192. Les propriétés opaqueBackground et scrollRect de la classe DisplayObject sont liées à la mise en cache sous forme de bitmap par le biais de la propriété cacheAsBitmap. Bien que ces trois propriétés soient indépendantes l’une de l’autre, opaqueBackground et scrollRect ne sont utiles que lorsqu’un objet est mis en cache sous forme de bitmap. Les avantages des propriétés opaqueBackground et scrollRect en termes de performances ne sont visibles que si cacheAsBitmap est définie sur true. Pour plus d’informations sur le défilement du contenu des objets d’affichage, voir « Défilement horizontal ou vertical des objets d’affichage » à la page 185. Pour plus d’informations sur la définition d’un arrière-plan opaque, voir « Définition d’un arrière-plan opaque » à la page 192. Pour plus d’informations sur le masquage du canal alpha, qui demande que vous définissiez la propriété cacheAsBitmap sur true, voir « Masquage des objets d’affichage » à la page 197.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’activation de la mise en cache d’un objet d’affichage crée une surface dont les avantages sont multiples, par exemple pour accélérer le rendu des animations vectorielles complexes. Lorsque vous souhaitez activer la mise en cache, plusieurs scénarios sont disponibles. Il pourrait sembler avantageux de toujours activer la mise en cache pour améliorer les performances de votre fichier SWF. Cependant, dans certains cas, cette opération n’a aucun effet bénéfique et risque même parfois de ralentir le fichier. Cette section présente des cas où la mise en cache s’avère bénéfique, et d’autres où il est préférable d’utiliser les objets de façon normale. Les performances générales des données mises en cache dépendent de la complexité des données vectorielles de vos occurrences, de la quantité de modifications et de la définition, ou non, de la propriété opaqueBackground. Si vous modifiez de petites zones, la différence entre l’utilisation d’une surface et celle de données vectorielles sera négligeable. Vous pouvez dans ce cas tester les deux scénarios avant de déployer votre application. Quand utiliser la mise en cache sous forme de bitmap Ce qui suit est une série de scénarios dans lesquels vous pouvez voir les bénéfices significatifs qui résultent de la mise en cache sous forme de bitmap.
L’arrière-plan est rendu en tant que bitmap et peut être redessiné rapidement pour que l’animation soit lue beaucoup plus vite.
à l’aide de bornes de déroulement (propriété scrollRect). Ceci permet un déroulement de pixels rapide pour l’occurrence indiquée. Quand un utilisateur déroule l’occurrence d’objet d’affichage, Flash Player ou AIR fait défiler les pixels déroulés vers le haut et génère la zone nouvellement exposée au lieu de régénérer tout le champ de texte.
• Masquage du canal alpha : si vous utilisez le masquage du canal alpha, vous devez définir la propriété cacheAsBitmap sur true. Pour plus d’informations, voir « Masquage des objets d’affichage » à la page 197.
Par ailleurs, lorsque vous appliquez un filtre à un objet d’affichage, cacheAsBitmap est automatiquement définie sur true, même si vous l’avez explicitement définie sur false. Si vous supprimez tous les filtres appliqués à l’objet d’affichage, la propriété cacheAsBitmap retrouve la valeur précédemment définie. Quand éviter d’utiliser la mise en cache sous forme de bitmap L’utilisation à mauvais escient de cette fonction risque d’affecter les performances du fichier SWF. Avant d’utiliser la mise en cache sous forme de bitmap, tenez compte des considérations suivantes :
Un bitmap caché utilise beaucoup plus de mémoire qu’un objet d’affichage standard. Par exemple, si la taille d’une occurrence de Sprite sur la scène correspond à 250 pixels sur 250 pixels, elle est susceptible d’utiliser en cache 250 Ko au lieu d’1 Ko pour une occurrence de Sprite standard (non en cache).
MovieClip contient une animation ou une occurrence de Video). Par exemple, si vous faites pivoter ou transformez une occurrence, la différence entre la surface et les données vectorielles rend le traitement difficile et affecte le fichier SWF.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour activer la mise en cache d’un objet d’affichage sous forme de bitmap, définissez sa propriété cacheAsBitmap sur true : mySprite.cacheAsBitmap = true;
Une surface (bitmap en cache) n’est pas créée même quand cacheAsBitmap est défini sur true s’il se produit l’un ou l’autre des événements suivants :
• Il est impossible d’allouer de la mémoire pour l’image bitmap. Matrices de transformation des images bitmap mises en cache Adobe AIR 2.0 et les versions ultérieures (profil mobile) Dans les applications AIR pour périphériques mobiles, vous devriez définir la propriété cacheAsBitmapMatrix à chaque fois que vous définissez la propriété cacheAsBitmap. Définir cette propriété permet d’appliquer un large éventail de transformations à l’objet d’affichage sans déclencher un nouveau rendu. mySprite.cacheAsBitmap = true; mySprite.cacheAsBitmapMatrix = new Matrix();
• Rotation • Mise à l’échelle • Inclinaison • Modification de l’alpha (transparence comprise entre 0 et 100 %) Ces transformations sont appliquées directement à l’image bitmap mise en cache.
(généralement une valeur hexadécimale). L’arrière-plan est alors considéré comme un bitmap, ce qui permet d’optimiser les performances. Lorsque vous définissez cacheAsBitmap sur true et la propriété opaqueBackground sur une couleur donnée, la propriété opaqueBackground assure l’opacité du bitmap interne et un rendu plus rapide. Si vous ne définissez pas cacheAsBitmap sur true, la propriété opaqueBackground ajoute une forme carrée vectorielle opaque à l’arrière-plan de l’objet d’affichage. Elle ne crée pas automatiquement un bitmap.
Application de modes de fondu Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les modes de fondu supposent d’associer les couleurs d’une image (l’image de base) à celles d’une autre image (l’image mélangée) afin de produire une troisième image, qui est celle qui sera en fait affichée à l’écran. Chaque valeur de pixels d’une image est traitée avec la valeur de pixels correspondante de l’autre image afin d’obtenir un résultat présentant une valeur de pixels de position identique. Tous les objets d’affichage possèdent une propriété blendMode qui peut être définie sur l’un des modes de fondu cidessous. Les valeurs ci-dessous sont des constantes définies dans la classe BlendMode. Vous pouvez également utiliser les valeurs String (entre parenthèses) correspondant aux valeurs réelles des constantes.
Pixel Bender » à la page 310. (Pas de prise en charge en cas de rendu par processeur graphique.)
Vous pouvez utiliser les méthodes de la classe ColorTransform (flash.geom.ColorTransform) pour régler la couleur d’un objet d’affichage. Chaque objet d’affichage possède une propriété transform, qui est une occurrence de la classe Transform et contient des informations relatives aux diverses transformations appliquées à l’objet d’affichage (rotation, changements d’échelle ou de position, etc.). Outre ces informations sur les transformations géométriques, la classe Transform comprend également une propriété colorTransform, qui est une occurrence de la classe ColorTransform et permet de régler les couleurs de l’objet d’affichage Pour accéder aux informations de transformation d’un objet d’affichage, utilisez le code suivant : var colorInfo:ColorTransform = myDisplayObject.transform.colorTransform;
// Make some color transformations here. // Commit the change. myDisplayObject.transform.colorTransform = colorInfo; La propriété color de la classe ColorTransform permet d’affecter une valeur de couleur rouge, vert, bleu (RVB) déterminée à l’objet d’affichage. L’exemple suivant utilise la propriété color pour changer en bleu la couleur de l’objet d’affichage square lorsque l’utilisateur clique sur le bouton blueBtn :
Modification des effets de couleur et de luminosité à l’aide du code Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Supposons qu’un objet d’affichage comporte plusieurs couleurs (par exemple une photo numérique) et que vous n’ayez pas l’intention de modifier la couleur de l’ensemble de l’objet, mais uniquement celle d’un de ses éléments sur la base des couleurs existantes. Dans ce scénario, la classe ColorTransform comprend une série de propriétés de multiplication et de dominante permettant d’effectuer ce type de réglage. Les propriétés de multiplication, appelées redMultiplier, greenMultiplier, blueMultiplier et alphaMultiplier, fonctionnent comme des filtres photographiques de couleur (ou des lunettes à verres de couleur) et amplifient ou diminuent certaines couleurs de l’objet d’affichage. Les propriétés de dominante (redOffset, greenOffset, blueOffset et alphaOffset) permettent d’ajouter à l’objet une quantité supplémentaire d’une certaine couleur, ou d’indiquer la valeur minimale que peut avoir une couleur particulière. Ces propriétés de multiplication et de dominante sont identiques aux réglages de couleurs avancés relatifs aux symboles de clips dans l’outil de programmation Flash lorsque vous sélectionnez Paramètres avancés dans le menu déroulant Couleur de l’Inspecteur des propriétés. Le code suivant charge une image JPEG et lui applique une transformation de couleur, qui ajuste les canaux rouge et vert lorsque le pointeur de la classe se déplace le long des axes x et y. Dans ce cas précis, comme aucune valeur de dominante n’est spécifiée, les valeurs de chaque canal colorimétrique seront un pourcentage de la valeur de couleur originale de l’image, c’est-à-dire que la valeur maximale de rouge ou de vert d’un pixel donné sera la quantité originale de vert ou de rouge de ce pixel.
La propriété rotation permet de faire pivoter les objets d’affichage. Vous pouvez lire cette valeur pour savoir si un objet a été soumis à une rotation. Vous pouvez également la définir sur un nombre (exprimé en degrés) représentant le montant de rotation à appliquer à l’objet. Par exemple, cette ligne de code fait pivoter l’objet square de 45 degrés (un huitième de tour complet) : square.rotation = 45;
« Utilisation de la géométrie » à la page 218.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous pouvez contrôler la transparence d’un objet d’affichage de sorte à le rendre partiellement (ou totalement) transparent, ou modifier la transparence pour créer une impression d’apparition ou de disparition en fondu de l’objet. La propriété alpha de la classe DisplayObject définit la transparence (ou plus précisément l’opacité) d’un objet d’affichage. La propriété alpha peut être définie sur n’importe quelle valeur comprise entre 0 et 1, sachant que 0 correspond à une transparence totale et 1 à une opacité totale. Par exemple, le code suivant rend l’objet myBall transparent à 50 % lors d’un clic de souris : function fadeBall(event:MouseEvent):void { myBall.alpha = .5; } myBall.addEventListener(MouseEvent.CLICK, fadeBall);
Vous pouvez utiliser un objet d’affichage comme masque pour créer un « trou » laissant apparaître le contenu d’un autre objet.
Pour indiquer qu’un objet d’affichage sera le masque d’un autre objet d’affichage, définissez l’objet masque comme propriété mask de l’objet à masquer : Dernière mise à jour le 27/4/2013
Il est impossible d’utiliser un masque pour en masquer un autre. Il est impossible de définir la propriété _alpha d’un objet d’affichage servant de masque. Seuls les remplissages sont utilisés dans un objet d’affichage employé comme masque ; les traits sont ignorés. AIR 2 Si un objet d’affichage masqué est mis en cache en définissant les propriétés cacheAsBitmap et cacheAsBitmapMatrix, le masque doit correspondre à un enfant de l’objet d’affichage masqué. De même, si l’objet d’affichage masqué est un descendant d’un conteneur d’objet d’affichage mis en cache, le masque et l’objet d’affichage doivent tous deux être des descendants du conteneur. Si l’objet masqué est un descendant de plusieurs conteneurs d’objet d’affichage mis en cache, le masque doit être un descendant du conteneur mis en cache le plus proche de l’objet masqué dans la liste d’affichage.
Vous pouvez utiliser un objet d’affichage pour masquer le texte défini dans une police de périphérique. Dans ce cas, le cadre de sélection rectangulaire du masque est utilisé comme forme de masquage. Ainsi, si vous créez un masque objet d’affichage non rectangulaire pour un texte de police de périphérique, le masque qui apparaît dans le fichier SWF prend la forme du cadre de sélection rectangulaire du masque, et non celle du masque en tant que tel.
Le masquage du canal alpha est pris en charge si le masque et les objets d’affichage masqués utilisent la mise en cache sous forme de bitmap, comme illustré ci-après : // maskShape is a Shape instance which includes a gradient fill. mySprite.cacheAsBitmap = true; maskShape.cacheAsBitmap = true; mySprite.mask = maskShape;
Dans l’exemple suivant, un fichier d’image externe est chargé sur la scène. Cette image (ou, plus précisément, l’occurrence de Loader dans laquelle elle est chargée) correspondra à l’objet d’affichage masqué. Un ovale dégradé (centre noir uni dont les bords deviennent progressivement transparents) est dessiné sur l’image. Il s’agit-là du masque alpha. La mise en cache sous forme de bitmap est activée pour les deux objets d’affichage. L’ovale est défini en tant que masque de l’image, puis peut être déplacé. // This code assumes it's being run within a display object container // such as a MovieClip or Sprite instance. import import import import import
également à jour l’écran à chaque exécution. Supposons par exemple que vous souhaitez créer une animation simple, telle qu’une balle qui traverse l’écran. ActionScript comprend un mécanisme simple qui permet de suivre le passage du temps et de mettre à jour l’écran en conséquence. En d’autres termes, vous pourriez écrire un code qui déplace la balle d’un petit incrément à chaque fois jusqu’à ce qu’elle atteigne sa destination. Après chaque déplacement, l’écran serait mis à jour, afin que l’utilisateur puisse visualiser le mouvement à l’écran. D’un point de vue pratique, il est logique de synchroniser l’animation par script avec la cadence du fichier SWF (en d’autres termes, de modifier une animation à chaque fois qu’une nouvelle image s’affiche ou devrait s’afficher), puisque cela permet de définir la fréquence des mises à jour de l’écran par Flash Player ou AIR. Chaque objet d’affichage possède un événement enterFrame qui est diffusé en fonction de la cadence d’affichage du fichier SWF (un événement par image). La plupart des développeurs qui créent une animation par script utilisent l’événement enterFrame pour générer des actions répétées au fil du temps. Vous pourriez écrire du code qui écoute l’événement enterFrame, déplace la balle animée d’un incrément déterminé à chaque image et, lorsque l’écran est mis à jour (à chaque image), la balle est redessinée à sa nouvelle position, créant ainsi un mouvement.
Timer. Une occurrence de Timer déclenche une notification d’événement après un délai horaire donné. Il est donc possible d’écrire du code effectuant une animation sur la base de l’événement timer de la classe Timer, en définissant un intervalle très court (une fraction de seconde). Pour plus d’informations sur l’utilisation de la classe Timer, voir « Contrôle des intervalles temporels » à la page 4. Dans l’exemple suivant, une occurrence circulaire de Sprite, appelée circle, est créée sur la scène. Lorsque l’utilisateur clique sur le cercle, une séquence animée par script débute et entraîne un fondu de circle (sa propriété alpha diminue) jusqu’à ce qu’il soit complètement transparent : import flash.display.Sprite; import flash.events.Event; import flash.events.MouseEvent; // draw a circle and add it to the display list var circle:Sprite = new Sprite(); circle.graphics.beginFill(0x990000); circle.graphics.drawCircle(50, 50, 50); circle.graphics.endFill(); addChild(circle); // When this animation starts, this function is called every frame. // The change made by this function (updated to the screen every Le même code permet, par exemple, de créer un mouvement animé au lieu d’un fondu. En substituant une autre propriété à alpha dans la fonction qui écoute l’événement enterFrame, cette propriété est animée. Par exemple, remplacer la ligne circle.alpha -= .05;
Orientation de la scène AIR 2.0 et les versions ultérieures Les périphériques mobiles réorientent généralement l’interface utilisateur de sorte à assurer un affichage à la verticale lorsque l’utilisateur fait pivoter le périphérique. Si vous activez l’orientation automatique dans votre application, le périphérique conserve l’orientation adéquate de l’écran, mais il vous incombe de vérifier que le contenu s’affiche correctement lorsque le format de la scène change. Si vous désactivez l’orientation automatique, l’écran du périphérique reste fixe, à moins que vous ne modifiiez l’orientation manuellement. Les applications AIR s’exécutent sur divers systèmes d’exploitation et périphériques mobiles. Le comportement d’orientation sous-jacent risque de varier selon le système d’exploitation, voire selon le périphérique sur un même système d’exploitation. Une stratégie de création simple adaptée à tous les périphériques et systèmes d’exploitation consiste à activer l’orientation automatique et à écouter les événements resize de l’objet Stage pour déterminer lorsqu’il est nécessaire d’actualiser la mise en forme de l’application. Si l’application prend en charge le format portrait uniquement ou le format paysage uniquement, vous pouvez également désactiver l’orientation automatique et définir le format géré dans le descripteur d’application AIR. Cette stratégie assure un comportement cohérent et sélectionne l’orientation la « plus » adaptée au format sélectionné. Par exemple, si vous activez le format paysage, l’orientation choisie convient aux périphériques dotés de claviers coulissants (en mode paysage).
L’orientation est indiquée relativement à la position normale du périphérique. Sur la plupart des périphériques, il existe une position verticale clairement identifiable. Cette position est considérée comme l’orientation par défaut. Les trois autres orientations possibles sont les suivantes : rotated left, rotated right et upside down. La classe StageOrientation intègre les constantes de type chaîne à utiliser lors de la définition ou de la comparaison de valeurs d’orientation. La classe Stage définit deux propriétés qui indiquent l’orientation, à savoir :
Remarque : l’orientation du périphérique n’est pas toujours disponible si l’application vient de démarrer ou si le périphérique est posé à plat. Dans ces cas de figure, l’orientation indiquée du périphérique correspond à unknown.
Pour identifier le format de la scène, il suffit de comparer la largeur et la hauteur actuelles de la scène : var aspect:String = this.stage.stageWidth >= this.stage.stageHeight ? StageAspectRatio.LANDSCAPE : StageAspectRatio.PORTRAIT;
Si vous spécifiez le format paysage ou portrait et activez l’orientation automatique, AIR définit l’orientation automatique au format spécifié. Modification des dimensions de la scène En cas de modification des dimensions de la scène, le contenu de cette dernière est mis à l’échelle et repositionné comme stipulé par les propriétés scaleMode et align de l’objet Stage. Dans la plupart des cas, il n’est pas recommandé de se fier au comportement automatique défini par les paramètres scaleMode de l’objet Stage. Pour prendre en charge plusieurs formats, il est préférable de modifier la mise en forme des graphiques et des composants ou de rafraîchir ces derniers. (Une logique de mise en forme souple présente également l’avantage d’assurer un meilleur fonctionnement de l’application sur des périphériques aux tailles d’écran et formats distincts.) L’illustration suivante présente les effets des différents paramètres scaleMode lors de la rotation d’un périphérique mobile standard :
L’objet Stage distribue deux types d’événements, dont vous disposez pour détecter les changements d’orientation et réagir à ces derniers. Les événements resize et orientationChange de la scène sont tous deux distribués si l’orientation automatique est activée. Privilégiez l’événement resize si vous vous fiez à l’orientation automatique pour assurer une position verticale à l’affichage. Lorsque la scène distribue un événement resize, changez la disposition de votre contenu ou redessinez-le si nécessaire. L’événement resize n’est distribué que si le mode de mise à l’échelle de la scène est défini sur noScale. L’événement orientationChange permet également de détecter les changements d’orientation. L’événement orientationChange n’est distribué que si l’orientation automatique est activée.
AIR 2.6 et les versions ultérieures Vous pouvez contrôler l’orientation de la scène via la méthode setOrientation() ou setAspectRatio() de l’objet Stage. Définition de l’orientation de la scène Vous pouvez définir l’orientation de la scène à l’exécution à l’aide de la méthode setOrientation() de l’objet Stage. Utilisez les constantes de chaîne définies par la classe StageOrientation pour spécifier l’orientation de votre choix : this.stage.setOrientation( StageOrientation.ROTATED_RIGHT );
{ trace( orientation ); } Le moteur d’exécution choisit l’une des deux orientations possibles pour le format spécifié. Il est possible que ce choix ne corresponde pas à l’orientation du périphérique. Par exemple, l’orientation par défaut est préférée à l’orientation à l’envers (AIR 3.2 et les versions antérieures) et l’orientation convenant au clavier coulissant est préférée à l’orientation opposée.
StageAspectRatio.ANY. Si vous définissez Stage.autoOrients sur true et appelez setAspectRatio(StageAspectRatio.ANY), votre application a la capacité de réorienter toutes les orientations (paysage vers la gauche, paysage vers la droite, portait et portrait à l’envers). Autre nouveauté dans AIR 3.3 : le format est persistent et toute rotation du périphérique est soumise à l’orientation spécifiée. Exemple : définition de l’orientation de la scène de façon à ce qu’elle corresponde à l’orientation du périphérique L’exemple suivant illustre une fonction qui met à jour l’orientation de la scène afin qu’elle corresponde à celle du périphérique. La propriété deviceOrientation de la scène indique l’orientation physique du périphérique, même si l’orientation automatique est désactivée. function refreshOrientation( theStage:Stage ):void { switch ( theStage.deviceOrientation ) { case StageOrientation.DEFAULT: theStage.setOrientation( StageOrientation.DEFAULT ); break; case StageOrientation.ROTATED_RIGHT: theStage.setOrientation( StageOrientation.ROTATED_LEFT ); break; case StageOrientation.ROTATED_LEFT: theStage.setOrientation( StageOrientation.ROTATED_RIGHT ); break; case StageOrientation.UPSIDE_DOWN: theStage.setOrientation( StageOrientation.UPSIDE_DOWN ); break; default: //No change Les éléments d’affichage externes suivants peuvent être chargés dans une application ActionScript 3.0 :
ActionScript peuvent être chargés. En d’autres termes, les fichiers SWF qui contiennent des données incorporées, telles qu’images et son, peuvent être chargées, mais pas les fichiers SWF contenant du code exécutable.
• Fichier AVM1 SWF : fichier SWF écrit en ActionScript 1.0 ou 2.0. (non pris en charge sur les applications mobiles AIR) Vous chargez ces ressources par le biais de la classe Loader.
Les objets Loader permettent de charger des fichiers SWF et des fichiers graphiques dans une application. La classe Loader est une sous-classe de la classe DisplayObjectContainer. La liste d’affichage d’un objet Loader ne comporte qu’un seul objet d’affichage enfant : l’objet d’affichage qui représente le fichier SWF ou graphique qu’il charge. Lorsque vous ajoutez un objet Loader à la liste d’affichage, comme dans le code ci-dessous, vous ajoutez également l’objet d’affichage enfant chargé à la liste d’affichage, une fois le chargement effectué : var pictLdr:Loader = new Loader(); var pictURL:String = "banana.jpg" var pictURLReq:URLRequest = new URLRequest(pictURL); pictLdr.load(pictURLReq); this.addChild(pictLdr);
{ container.addChild(pictLdr.content); Lorsque le chargement du fichier débute, un objet LoaderInfo est créé. Un objet LoaderInfo fournit diverses informations sur le chargement : progression, adresses URL du chargeur et du chargé, nombre d’octets total de l’objet multimédia et dimensions nominales (hauteur et largeur) de celui-ci. Par ailleurs, un objet LoaderInfo distribue les événements qui permettent de suivre la progression du chargement.
Vous pouvez accéder à l’objet LoaderInfo en tant que propriété de l’objet Loader et de l’objet d’affichage chargé. Dès que le chargement débute, vous pouvez accéder à l’objet LoaderInfo par le biais de la propriété contentLoaderInfo de l’objet Loader. Lorsque le chargement de l’objet d’affichage est terminé, vous pouvez également accéder à l’objet LoaderInfo en tant que propriété de cet objet chargé par le biais de la propriété loaderInfo de l’objet d’affichage. La propriété loaderInfo de l’objet d’affichage chargé se réfère au même objet LoaderInfo que la propriété contentLoaderInfo de l’objet Loader. En d’autres termes, un objet LoaderInfo est partagé entre un objet chargé et l’objet Loader qui l’a chargé (entre le chargeur et le chargé). Pour accéder aux propriétés du contenu chargé, il est recommandé d’ajouter un écouteur d’événement à l’objet LoaderInfo, comme indiqué dans le code suivant : import flash.display.Loader; import flash.display.Sprite; import flash.events.Event; var ldr:Loader = new Loader(); var urlReq:URLRequest = new URLRequest("Circle.swf"); ldr.load(urlReq); ldr.contentLoaderInfo.addEventListener(Event.COMPLETE, loaded); addChild(ldr); function loaded(event:Event):void { var content:Sprite = event.target.content; content.scaleX = 2; }
Lorsque vous chargez un fichier externe dans Flash Player ou AIR par le biais de la méthode load() ou loadBytes() de la classe Loader, vous pouvez indiquer le paramètre context. Ce paramètre est un objet LoaderContext.
BitmapData.draw() pour accéder aux données de l’image chargées. Notez qu’un fichier SWF extrait d’un autre domaine que celui de l’objet Loader peut appeler Security.allowDomain() pour autoriser un domaine déterminé.
Il existe des restrictions concernant le chargement et la compilation de code à l’exécution sur les périphériques iOS. En raison de ces restrictions, vous constaterez certaines différences nécessaires dans la tâche de chargement des fichiers SWF externes dans votre application :
SWF contenant du code ne peut être chargé depuis une source externe (via un réseau, par exemple). Lors de la création du package de l’application, le code ActionScript des fichiers SWF du package d’application est compilé en code natif pour périphériques iOS.
ActionScript dans le fichier SWF chargé restent en mémoire et sont accessibles par le code ActionScript.
LoaderContext spécifiant le domaine d’application principal et transmettre cet objet LoaderContext à l’appel de méthode Loader.load(). Si vous tentez de charger un fichier SWF dans un domaine d’application autre que le domaine d’application SWF principal, une erreur se produit. Cela est vrai même si le fichier SWF chargé ne contient que des éléments visuels sans code ActionScript. L’exemple suivant montre le code à utiliser pour charger le SWF depuis le package d’application dans le domaine d’application du fichier SWF principal : var loader:Loader = new Loader(); var url:URLRequest = new URLRequest("swfs/SecondarySwf.swf"); var loaderContext:LoaderContext = new LoaderContext(false, ApplicationDomain.currentDomain, null); loader.load(url, loaderContext);
Pour les versions d’AIR antérieures à 3.6, le code est retiré de tous les fichiers SWF, à l’exception du fichier d’application SWF principal, au cours du processus de compilation. Les fichiers SWF ne contenant que des éléments visuels peuvent être inclus dans le package d’application et chargés à l’exécution, mais pas le code. Si vous tentez de charger un fichier SWF contenant du code ActionScript, une erreur se produit. Cette erreur cause l’apparition d’un message d’erreur « ActionScript non compilé » dans l’application. Voir aussi Packaging and loading multiple SWFs in AIR apps on iOS (disponible en anglais uniquement).
Flash Player 9 et les versions ultérieures et Adobe AIR 1.0 et les versions ultérieures requièrent Flash Professional CS5.5 Pour faciliter le préchargement de la bibliothèque RSL (Remote Shared Library), Flash Professional CS5.5 intègre à présent les classes fl.display.ProLoader et fl.display.ProLoaderInfo. Ces classes reflètent les classes flash.display.Loader et flash.display.LoaderInfo, mais assurent un chargement plus cohérent. La classe ProLoader permet en particulier de charger les fichiers SWF qui font appel à Text Layout Framework (TLF) lors d’un préchargement RSL. A l’exécution, les fichiers SWF qui préchargent d’autres fichiers SWF ou des fichiers SWZ, tels que TLF, nécessitent un fichier d’enveloppe SWF à usage interne uniquement. Cette couche complémentaire de complexité imposée par le fichier d’enveloppe SWF entraîne parfois un comportement inattendu. La classe ProLoader résout ce problème en permettant de charger les fichiers comme des fichiers SWF standard. La solution adoptée par la classe ProLoader est transparente du point de vue de l’utilisateur et ne requiert pas de traitement particulier dans ActionScript. La classe ProLoader charge par ailleurs correctement les contenus SWF standard. Dans Flash Professional CS 5.5 et ultérieur, vous pouvez remplacer la classe Loader par la classe ProLoader dans tous les cas de figure en toute sécurité. Exportez ensuite l’application vers Flash Player 10.2 ou ultérieur, afin que la classe ProLoader puisse accéder à la fonctionnalité ActionScript requise. Vous pouvez également faire appel à la classe ProLoader si vous ciblez des versions antérieures de Flash Player qui prennent en charge ActionScript 3.0. Toutefois, seul Flash Player 10.2 ou ultérieur exploite pleinement les fonctions de Proloader. Utilisez toujours la classe ProLoader si vous faites appel à TLF dans Flash Professional CS5.5 ou ultérieur. L’utilisation de ProLoader est superflue dans les environnements autres que Flash Professional. Important : pour les fichiers SWF publiés dans Flash Professional CS5.5 et ultérieur, il est toujours possible d’utiliser les classes fl.display.ProLoader et fl.display.ProLoaderInfo au lieu des classes flash.display.Loader et flash.display.LoaderInfo. Problèmes résolus par la classe ProLoader La classe ProLoader résout les problèmes que la classe Loader existante, de par sa conception, ne prenait pas en charge. Ces problèmes résultent du préchargement RSL de bibliothèques TLF. Ils concernent spécifiquement les fichiers SWF qui chargent d’autres fichiers SWF par le biais d’un objet Loader. Les problèmes résolus sont les suivants :
De ce fait, les communications émanant du fichier SWF de chargement ciblent directement le fichier SWF chargé.
Mise à jour du code en vue d’utiliser ProLoader au lieu de Loader Etant donné que la classe ProLoader reflète la classe Loader, substituer une classe à l’autre dans le code ne présente aucune difficulté. L’exemple suivant illustre la mise à jour du code existant en vue d’utiliser la nouvelle classe :
• Utilisation des propriétés et méthodes des objets d’affichage Pour obtenir les fichiers d’application de cet exemple, voir www.adobe.com/go/learn_programmingAS3samples_flash_fr. Les fichiers d’application SpriteArranger résident dans le dossier Examples/SpriteArranger. L’application se compose des fichiers suivants :
L’application SpriteArranger permet à l’utilisateur d’ajouter divers objets d’affichage au rectangle de la zone de dessin à l’écran. La classe DrawingCanvas définit une zone de dessin, soit un type de conteneur d’objets d’affichage, à laquelle l’utilisateur peut ajouter des formes à l’écran. Ces formes sont des occurrences de l’une des sous-classes de la classe GeometricSprite.
Programmation de l’affichage
Dans Flex, tous les objets d’affichage enfant ajoutés à un objet Container doivent appartenir à une classe issue de la classe mx.core.UIComponent. Cette application ajoute une occurrence de la classe DrawingCanvas en tant qu’enfant d’un objet mx.containers.VBox, ainsi que le définit le code MXML dans le fichier SpriteArranger.mxml. Cet héritage est défini dans la déclaration de classe DrawingCanvas, comme suit : public class DrawingCanvas extends UIComponent
DrawingCanvas utilise les méthodes et propriétés de ces dernières. La classe DrawingCanvas étend la classe Sprite et cet héritage est défini dans la déclaration de classe DrawingCanvas, comme suit : public class DrawingCanvas extends Sprite
La méthode constructeur DrawingCanvas() définit un objet Rectangle, bounds, qui est une propriété utilisée ultérieurement lors du tracé du contour de la zone de dessin. Elle appelle ensuite la méthode initCanvas(), comme suit : this.bounds = new Rectangle(0, 0, w, h); initCanvas(fillColor, lineColor);
• Les méthodes addShape() et describeChildren(), décrites à la section « Ajout d’objets d’affichage au rectangle de la zone de dessin » à la page 214
Chaque objet d’affichage susceptible d’être ajouté par l’utilisateur au rectangle de la zone de dessin est une occurrence de l’une des sous-classes suivantes de la classe GeometricSprite :
• SquareSprite La classe GeometricSprite définit la méthode drawShape(), qui est affinée dans les définitions de remplacement de chaque sous-classe de GeometricSprite. Pour plus d’informations, voir ci-après « Ajout d’objets d’affichage au rectangle de la zone de dessin ». La classe GeometricSprite propose également les méthodes suivantes :
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lorsque l’utilisateur clique sur le bouton Add Shape, l’application appelle la méthode addShape() de la classe DrawingCanvas. Elle crée une occurrence de GeometricSprite en appelant la fonction constructeur appropriée de l’une des sous-classes de GeometricSprite, comme illustré dans l’exemple suivant :
DisplayObject), de sorte que chaque objet d’affichage ajouté au rectangle de la zone de dessin soit légèrement transparent, permettant ainsi à l’utilisateur de visualiser les objets placés derrière. La derrière ligne de la méthode addChild() ajoute le nouvel objet d’affichage à la liste enfant de l’occurrence de la classe DrawingCanvas, qui figure déjà dans la liste d’affichage. Le nouvel objet d’affichage apparaît alors sur la scène. L’interface de l’application comprend deux champs de texte, selectedSpriteTxt et outputTxt. Les propriétés de texte de ces champs sont mises à jour avec des informations relatives aux objets GeometricSprite ajoutés au rectangle de la zone de dessin ou sélectionnés par l’utilisateur. La classe GeometricSprite gère ces tâches de transmission d’informations en annulant la méthode toString() comme suit : public override function toString():String { return this.shapeType + " of size " + this.size + " at " + this.x + ", " + this.y; }
GeometricSprite. La méthode toString() pourrait par exemple renvoyer la valeur suivante pour une occurrence de CircleSprite récemment ajoutée à l’occurrence de DrawingCanvas : Circle of size 50 at 0, 0
Lorsque l’utilisateur clique sur une occurrence de GeometricSprite, l’application appelle le gestionnaire de l’événement onMouseDown(). Comme le montre le code ci-dessous, ce gestionnaire écoute les événements de clic gauche de souris dans la fonction constructeur de la classe GeometricSprite : this.addEventListener(MouseEvent.MOUSE_DOWN, onMouseDown);
(héritée de la classe DisplayObject) de la forme selectionIndicator : this.selectionIndicator.visible = true;
La méthode du gestionnaire d’événement onMouseDown() appelle également la méthode startDrag() (héritée de la classe Sprite), qui comprend le code suivant : var boundsRect:Rectangle = this.parent.getRect(this.parent); boundsRect.width -= this.size; boundsRect.height -= this.size; this.startDrag(false, boundsRect);
Lorsque l’utilisateur relâche le bouton de la souris, l’événement mouseUp est distribué. La méthode constructeur de DrawingCanvas configure l’écouteur d’événement suivant : this.addEventListener(MouseEvent.MOUSE_UP, onMouseUp);
(un autre objet GeometricSprite) lorsque le bouton de la souris est relâché. L’événement « mouse up » s’appliquerait à l’objet d’affichage en avant-plan, mais non à l’objet d’affichage déplacé par l’utilisateur. Ajouter l’écouteur à l’objet DrawingCanvas assure la gestion de l’événement.
Réorganisation de l’ordre de superposition des objets d’affichage Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’interface utilisateur de l’application comprend des boutons intitulés Move Back, Move Down, Move Up et Move to Front. Lorsque l’utilisateur clique sur l’un de ces boutons, l’application appelle la méthode correspondante de la classe DrawingCanvas, à savoir : moveToBack(), moveDown(), moveUp() ou moveToFront(). Par exemple, la méthode moveToBack() comporte le code suivant : public function moveToBack(shape:GeometricSprite):void { var index:int = this.getChildIndex(shape); if (index > 0) { this.setChildIndex(shape, 0); } Le package flash.geom contient des classes qui définissent des objets géométriques, tels que des points, des rectangles et des matrices de transformation. Vous utilisez ces classes pour définir les propriétés des objets qui sont utilisés dans d’autres classes.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le package flash.geom contient des classes qui définissent des objets géométriques, tels que des points, des rectangles et des matrices de transformation. Ces classes ne fournissent pas nécessairement de fonctionnalité par elles-mêmes ; néanmoins, elles sont utilisées pour définir les propriétés des objets utilisés dans d’autres classes. Toutes les classes de géométrie se basent sur la notion selon laquelle les emplacements à l’écran sont représentés comme un plan en deux dimensions. L’écran est traité comme un graphique plat avec un axe horizontal (x) et un axe vertical (y). Tout emplacement (ou point) à l’écran peut être représenté sous la forme d’une paire de valeurs x et y, appelées coordonnées de cet emplacement. Chaque objet d’affichage, y compris la scène, possède son propre espace de coordonnées. L’espace de coordonnées constitue le graphe d’un objet et permet de tracer la position des dessins, des objets d’affichage enfant, etc. L’origine occupe la position 0, 0 (soit l’intersection des axes x et y) et est placée dans l’angle supérieur gauche de l’objet d’affichage. La position de l’origine est systématiquement respectée pour la scène, mais pas nécessairement pour d’autres objets d’affichage. La taille des valeurs figurant sur l’axe x croît vers la droite et diminue vers la gauche. La coordonnée x des positions figurant sur la gauche de l’origine est négative. Cependant, contrairement aux systèmes de coordonnées classiques, la valeur des coordonnées de l’axe y croît vers le bas de l’écran et diminue vers le haut dans le moteur d’exécution de Flash. La coordonnée y des valeurs situées au-dessus de l’origine est négative. Puisque l’angle supérieur gauche de la scène correspond à l’origine de son espace de coordonnées, la coordonnée x de la plupart des objets de la scène est supérieure à 0 et inférieure à la largeur de la scène. La coordonnée y d’un même objet est supérieure à 0 et inférieure à la hauteur de la scène. Vous pouvez utiliser des occurrences de la classe Point pour représenter des points individuels dans un espace de coordonnées. Vous pouvez créer une occurrence de Rectangle pour représenter une région rectangulaire dans un espace de coordonnées. Les utilisateurs chevronnés peuvent utiliser une occurrence de Matrix pour appliquer des transformations multiples ou complexes à un objet d’affichage. De nombreuses transformations simples (rotation, position, et changements d’échelle, par exemple) peuvent être appliquées directement à un objet d’affichage à l’aide des propriétés de ce dernier. Pour plus d’informations sur l’application de transformations à l’aide des propriétés d’un objet d’affichage, voir « Manipulation des objets d’affichage » à la page 180.
Utilisation de la géométrie
La liste de référence suivante contient des termes de géométrie importants : Coordonnées cartésiennes Les coordonnées sont généralement écrites sous la forme d’une paire de nombres (5, 12 ou 17, -23). Les deux nombres sont la coordonnée x et la coordonnée y, respectivement. Espace de coordonnées Représentation graphique des coordonnées contenues dans un objet d’affichage, par rapport
Origine Point d’intersection des axes x et y dans un espace de coordonnées. Ce point a les coordonnées 0, 0. Point Emplacement unique dans un espace de coordonnées. Dans le système de coordonnées 2D utilisé dans ActionScript, la position sur les axes x et y (en d’autres termes, les coordonnées du point) définit ce dernier. Point d’alignement Dans un objet d’affichage, origine (coordonnées 0, 0) de son espace de coordonnées. Mise à l’échelle Taille relative d’un objet par rapport à sa taille d’origine. Mettre un objet à l’échelle consiste à modifier sa taille en l’étirant ou en le rétrécissant. Translation Conversion des coordonnées d’un point d’un espace de coordonnées à un autre. Transformation Modification des caractéristiques visuelles d’un graphique (rotation de l’objet, modification de son
Axe x Axe horizontal dans le système de coordonnées en 2 dimensions utilisé dans ActionScript. Axe y Axe vertical dans le système de coordonnées en 2 dimensions utilisé dans ActionScript.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Un objet Point définit une paire de coordonnées cartésiennes. Il représente un emplacement dans un système de coordonnées à deux dimensions, dans lequel x est l’axe horizontal et y l’axe vertical. Pour définir un objet Point, vous définissez ses propriétés x et y comme suit : import flash.geom.*; var pt1:Point = new Point(10, 20); // x == 10; y == 20 var pt2:Point = new Point(); pt2.x = 10; pt2.y = 20;
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous pouvez utiliser la méthode distance() de la classe Point pour calculer la distance entre deux points dans un espace de coordonnées. Par exemple, le code suivant calcule la distance entre les points d’alignement de deux objets d’affichage, circle1 et circle2, dans le même conteneur d’objet d’affichage : import flash.geom.*; var pt1:Point = new Point(circle1.x, circle1.y); var pt2:Point = new Point(circle2.x, circle2.y); var distance:Number = Point.distance(pt1, pt2);
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Si deux objets d’affichage résident dans des conteneurs d’objet d’affichage distincts, ils peuvent figurer dans des espaces de coordonnées distincts. Vous pouvez utiliser la méthode localToGlobal() de la classe DisplayObject pour traduire les coordonnées dans le même espace de coordonnées (global), celui de la scène. Par exemple, le code suivant calcule la distance entre les points d’alignement de deux objets d’affichage, circle1 et circle2, dans les différents conteneurs d’objet d’affichage : import flash.geom.*; var pt1:Point = new Point(circle1.x, circle1.y); pt1 = circle1.localToGlobal(pt1); var pt2:Point = new Point(circle2.x, circle2.y); pt2 = circle2.localToGlobal(pt2); var distance:Number = Point.distance(pt1, pt2);
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous pouvez utiliser la méthode polar() de la classe Point pour déplacer un objet d’affichage d’une distance et d’un angle spécifiques. Par exemple, le code suivant déplace l’objet myDisplayObject en fonction d’une distance de 100 pixels et d’un angle de 60° : import flash.geom.*; var distance:Number = 100; var angle:Number = 2 * Math.PI * (90 / 360); var translatePoint:Point = Point.polar(distance, angle); myDisplayObject.x += translatePoint.x; myDisplayObject.y += translatePoint.y;
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous pouvez utiliser des objets Point avec les propriétés et les méthodes suivantes :
Redimensionnement et repositionnement des objets Rectangle Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Il existe de nombreuses façons de redimensionner et de repositionner des objets Rectangle. Vous pouvez redimensionner directement l’objet Rectangle en modifiant ses propriétés x et y. Ce changement n’a aucune incidence sur la largeur ou la hauteur de l’objet Rectangle.
Utilisation de la géométrie
Vous pouvez également redimensionner un objet Rectangle à l’aide de la méthode inflate(), qui inclut deux paramètres, dx et dy. Le paramètre dx représente le déplacement à partir du centre des côtés droit et gauche de l’objet Rectangle, exprimé en pixels. Le paramètre dy représente le déplacement à partir du centre du haut et du bas de l’objet Rectangle, exprimé en pixels. import flash.geom.Rectangle; var x1:Number = 0; var y1:Number = 0; var width1:Number = 100; var height1:Number = 50; var rect1:Rectangle = new Rectangle(x1, y1, width1, height1); trace(rect1) // (x=0, y=0, w=100, h=50) rect1.inflate(6,4); trace(rect1); // (x=-6, y=-4, w=112, h=58)
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous utilisez la méthode union() pour rechercher la région rectangulaire formée par les limites de deux rectangles : import flash.display.*; import flash.geom.Rectangle; var rect1:Rectangle = new Rectangle(0, 0, 100, 100); trace(rect1); // (x=0, y=0, w=100, h=100) var rect2:Rectangle = new Rectangle(120, 60, 100, 100); trace(rect2); // (x=120, y=60, w=100, h=100) trace(rect1.union(rect2)); // (x=0, y=0, w=220, h=160)
Les objets Rectangle sont utilisés dans les propriétés et méthodes suivantes : Classe
La classe Matrix représente une matrice de transformation qui détermine le mappage des points d’un espace de coordonnées à l’autre. Pour appliquer diverses transformations graphiques à un objet d’affichage, vous pouvez définir les propriétés d’un objet Matrix, puis appliquer cet objet à la propriété matrix d’un objet Transform que vous appliquez ensuite comme propriété transform de l’objet d’affichage. Ces fonctions de transformation incluent la translation (repositionnement de x et y), la rotation, le redimensionnement et l’inclinaison.
Utilisation de la géométrie
Remarque : la classe ColorTransform est également comprise dans le package flash.geometry. Cette classe sert à définir la propriété colorTransform d’un objet Transform. Etant donné qu’elle n’applique aucune transformation géométrique, elle n’est pas traitée ici. Pour plus d’informations, voir la classe ColorTransform dans le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’exemple d’application DisplayObjectTransformer présente de nombreuses fonctions permettant d’utiliser la classe Matrix pour transformer un objet d’affichage, notamment :
• Redimensionnement de l’objet d’affichage • Translation (repositionnement) de l’objet d’affichage • Inclinaison de l’objet d’affichage L’application fournit une interface permettant d’ajuster les paramètres de la transformation de matrice, comme suit :
Pour obtenir les fichiers d’application de cet exemple, voir www.adobe.com/go/learn_programmingAS3samples_flash_fr. Les fichiers d’application DisplayObjectTransformer se trouvent dans le dossier Samples/DisplayObjectTransformer. L’application se compose des fichiers suivants : Fichier
La classe MatrixTransformer comprend des méthodes statiques qui appliquent des transformations géométriques d’objets Matrix. Méthode transform() La méthode transform() comprend des paramètres associés à chaque élément suivant :
Dernière mise à jour le 27/4/2013
Utilisation de la géométrie
{ angle = } if (unit == Elle transmet ensuite ces valeurs, avec la propriété matrix de la propriété transform de l’objet d’affichage, à la méthode Matrix.transform(), comme suit : tempMatrix = MatrixTransformer.transform(tempMatrix, xScaleSlider.value, yScaleSlider.value, dxSlider.value, dySlider.value, rotationSlider.value, skewSlider.value, skewSide );
L’API de dessin est le nom des fonctionnalités intégrées à ActionScript qui permettent de créer des graphiques vectoriels (lignes, courbes, formes, remplissages et dégradés) et de les afficher à l’aide d’ActionScript. Ces fonctionnalités sont prises en charge par la classe flash.display.Graphics. ActionScript permet de dessiner dans une occurrence d’un objet de type Shape, Sprite ou MovieClip, à l’aide de la propriété graphics définie dans chacune de ces classes (la propriété graphics de ces classes est en fait une occurrence de la classe Graphics). Si vous n’avez pas l’habitude de « dessiner » par code, la classe Graphics comprend plusieurs méthodes qui facilitent le tracé de formes courantes (cercles, ellipses, rectangles et rectangles à coins arrondis). Ces tracés peuvent être des lignes vides ou des formes remplies. Si vous avez besoin de fonctionnalités plus sophistiquées, la classe Graphics comporte aussi des méthodes destinées au tracé de lignes et de courbes de Bézier, qui peuvent être utilisées conjointement avec les fonctions trigonométriques de la classe Math pour créer n’importe quelle forme. Les moteurs d’exécution Flash (tels que Flash Player 10, Adobe AIR 1.5 et les versions ultérieures) prennent en charge une nouvelle API de dessin, qui vous permet de tracer intégralement des formes par programmation à l’aide d’une commande unique. Une fois que vous vous êtes familiarisé avec la classe Graphics et les tâches décrites dans « Bases d’utilisation de l’API de dessin », passez à « Utilisation avancée de l’API de dessin » à la page 243 pour en savoir plus sur ces fonctions. Concepts importants et terminologie La liste de référence suivante contient des termes importants relatifs à l’utilisation de l’API de dessin : Point d’ancrage L’un des deux points d’extrémité d’une courbe de Bézier. Point de contrôle Point qui définit la direction et la forme d’une courbe de Bézier. Cette ligne courbe ne touche jamais
Espace de coordonnées Représentation graphique des coordonnées contenues dans un objet d’affichage, par rapport
Utilisation de l’API de dessin
Dégradé Transition progressive d’une couleur à une ou plusieurs autres couleurs (par opposition à une couleur unie). Point Emplacement unique dans un espace de coordonnées. Dans le système de coordonnées en 2 dimensions utilisé dans ActionScript, un point est défini par son emplacement le long de l’axe x et de l’axe y (les coordonnées du point). Courbe de Bézier quadratique Type de courbe défini par une formule mathématique déterminée. Dans ce type de
Mise à l’échelle Taille relative d’un objet par rapport à sa taille d’origine. Mettre un objet à l’échelle consiste à modifier
Trait Ligne de contour d’une forme constituée par le remplissage de cette ligne, ou forme ne possédant pas de remplissage. Translation Conversion des coordonnées d’un point d’un espace de coordonnées à un autre. Axe x Axe horizontal dans le système de coordonnées en 2 dimensions utilisé dans ActionScript. Axe y Axe vertical dans le système de coordonnées en 2 dimensions utilisé dans ActionScript.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Chaque objet Shape, Sprite et MovieClip possède une propriété graphics qui est une occurrence de la classe Graphics. La classe Graphics comporte des propriétés et des méthodes permettant de tracer des lignes, des remplissages et des formes. Pour disposer d’un objet d’affichage qui sera uniquement utilisé comme « toile de fond » pour un dessin, utilisez une occurrence de Shape. Une occurrence de Shape est mieux adaptée au dessin que les autres objets, car elle ne comporte pas les fonctionnalités (inutiles dans ce type d’utilisation) des classes Sprite et MovieClip. Par contre, si vous souhaitez créer un objet d’affichage qui servira de support à du contenu graphique mais doit également pouvoir contenir d’autres objets d’affichage, utilisez une occurrence de Sprite. Pour plus d’informations sur le choix des objets d’affichage en fonction de la tâche prévue, voir « Sélection d’une sous-classe de DisplayObject » à la page 179
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Tous les graphiques qu’il est possible de réaliser à l’aide d’une occurrence de la classe Graphics sont des tracés à l’aide de lignes et de courbes. Tous les dessins réalisés en ActionScript doivent donc suivre les mêmes étapes :
• Définition de la position de dessin initiale • Dessin de lignes, courbes et formes (éventuellement en déplaçant le point de traçage) • Le cas échéant, création d’un remplissage
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour utiliser la propriété graphics d’une occurrence de Shape, Sprite ou MovieClip, vous devez d’abord définir le style (épaisseur et couleur de la ligne, couleur de remplissage) à utiliser. A l’instar des outils de dessin d’Adobe® Flash® Professional ou de toute autre application de dessin, en ActionScript vous pouvez dessiner avec ou sans trait, et avec ou sans remplissage. Pour indiquer l’apparence du trait, utilisez la méthode lineStyle() ou lineGradientStyle(). Pour créer une ligne pleine, utilisez la méthode lineStyle(). Lors de l’appel de cette méthode, les valeurs les plus courantes à indiquer sont les trois premiers paramètres : épaisseur de ligne, couleur et alpha. Par exemple, la ligne de code suivante indique que la forme myShape doit tracer des lignes de deux pixels d’épaisseur, en rouge (0x990000) et avec une opacité de 75 % : myShape.graphics.lineStyle(2, 0x990000, .75);
Graphics.lineStyle() dans le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash. Pour créer une ligne dégradée, utilisez la méthode lineGradientStyle(). Pour plus d’informations sur cette méthode, voir « Création de lignes et de remplissages en dégradé » à la page 235. Pour créer une forme remplie, appelez les méthodes beginFill(), beginGradientFill(), beginBitmapFill() ou beginShaderFill() avant de débuter le dessin. La plus basique, beginFill(), accepte deux paramètres : la couleur de remplissage et, le cas échéant, la valeur alpha correspondante. Par exemple, pour tracer une forme avec un remplissage vert uni, utilisez le code suivant (on suppose ici que vous dessinez dans un objet nommé myShape) : myShape.graphics.beginFill(0x00FF00);
Une fois spécifié le style de ligne et de remplissage, l’étape suivante consiste à indiquer le point de départ du dessin. L’occurrence de Graphics possède un point de traçage, tout comme la pointe d’un crayon sur une feuille de papier. Quel que soit l’emplacement du point de traçage, il représente l’origine de l’action de dessin à venir. Initialement, un objet Graphics débute avec son point de traçage aux points 0,0 dans l’espace de coordonnées de l’objet dans lequel il dessine. Pour que le tracé débute en un autre point, appelez la méthode moveTo() avant d’appeler une des méthodes de dessin. Cet appel peut être comparé à l’action de lever la pointe du crayon du papier et de l’amener à un nouvel emplacement. Lorsque le point de traçage est en place, utilisez une série d’appels aux méthodes lineTo() (pour tracer des lignes droites) et curveTo() (pour tracer des courbes). Pendant l’opération de dessin, vous pouvez à tout moment appeler la méthode moveTo() pour amener le point de traçage à une nouvelle position sans dessiner. Si vous avez défini une couleur de remplissage, vous pouvez désactiver le remplissage en appelant la méthode endFill() pendant l’opération de dessin. Si vous n’avez pas tracé de forme fermée (autrement dit, si lors de l’appel de la méthode endFill() le point de traçage ne correspond pas au point de départ de la forme), lorsque vous appelez la méthode endFill(), le moteur d’exécution Flash ferme automatiquement la forme en traçant une ligne droite entre le point de traçage actuel et l’emplacement spécifié dans le dernier appel à la méthode moveTo(). Si vous avez débuté un remplissage et n’avez pas appelé endFill(), tout appel à beginFill() (ou à l’une des autres méthodes de remplissage) ferme le remplissage actif et en débute un nouveau.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lorsque vous appelez la méthode lineTo(), l’objet Graphics trace une ligne droite (en utilisant le style de ligne que vous avez spécifié) entre le point de traçage actuel et les coordonnées que vous transmettez en paramètres à cette méthode. Par exemple, cette ligne de code place le point de traçage aux coordonnées 100, 100 puis trace une ligne jusqu’au point 200, 200 : myShape.graphics.moveTo(100, 100); myShape.graphics.lineTo(200, 200);
// red triangle, starting at point 0, 0 triangle.graphics.beginFill(0xFF0000); triangle.graphics.moveTo(triangleHeight / 2, 0); triangle.graphics.lineTo(triangleHeight, triangleHeight); triangle.graphics.lineTo(0, triangleHeight); triangle.graphics.lineTo(triangleHeight / 2, 0); L’exemple suivant trace des objets circulaires rouges et verts avec une largeur et une hauteur de 100 pixels. Notez qu’en raison même de la nature de l’équation de Bézier, ces cercles ne sont pas parfaits :
Pour vous permettre de tracer plus commodément des formes courantes (cercles, ellipses, rectangles et rectangles à coins arrondis), ActionScript 3.0 comporte des méthodes qui tracent automatiquement ces formes. Ces méthodes sont drawCircle(), drawEllipse(), drawRect() et drawRoundRect(), et sont toutes définies dans la classe Graphics. Elles peuvent être utilisées à la place des méthodes lineTo() et curveTo(). Notez toutefois qu’il est nécessaire de spécifier des styles de ligne et de remplissage avant d’appeler ces méthodes. L’exemple suivant dessine des carrés bleus, rouges et verts avec une largeur et une hauteur de 100 pixels. Ce code utilise la méthode drawRect() et spécifie que l’opacité de la couleur de remplissage est de 50 % (0,5) : var squareSize:uint = 100; var square:Shape = new Shape(); square.graphics.beginFill(0xFF0000, 0.5); square.graphics.drawRect(0, 0, squareSize, squareSize); square.graphics.beginFill(0x00FF00, 0.5); square.graphics.drawRect(200, 0, squareSize, squareSize); square.graphics.beginFill(0x0000FF, 0.5); square.graphics.drawRect(400, 0, squareSize, squareSize); square.graphics.endFill(); this.addChild(square);
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’objet Graphics permet aussi de tracer des traits et des remplissages avec des dégradés au lieu de couleurs unies. Pour créer un trait dégradé, utilisez la méthode lineGradientStyle(). Pour créer un remplissage dégradé, utilisez la méthode beginGradientFill(). Ces deux méthodes reçoivent les mêmes paramètres. Les quatre premiers sont obligatoires : type, couleurs, transparences alpha et rapports. Les quatre suivants sont facultatifs mais peuvent être utiles pour plus de personnalisation.
GradientType.RADIAL.
Le cinquième paramètre, la matrice de transformation, est facultatif mais fréquemment utilisé, car il représente un moyen à la fois puissant et aisé de contrôler l’aspect du dégradé. Ce paramètre accepte une occurrence de l’objet Matrix. Le moyen le plus simple de créer un objet Matrix pour un dégradé consiste à utiliser la méthode createGradientBox() de la classe Matrix.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Utilisez les méthodes beginGradientFill() et lineGradientStyle() de la classe flash.display.Graphics pour définir les dégradés à utiliser dans des formes. Lorsque vous définissez un dégradé, vous fournissez une matrice comme l’un des paramètres de ces méthodes.
La façon la plus facile de définir la matrice est d’utiliser la méthode createGradientBox(), de la classe Matrix, qui définit un tableau utilisé pour définir le dégradé. Définissez l’échelle, la rotation et la position du dégradé à l’aide des paramètres transmis à la méthode createGradientBox(). La méthode createGradientBox() reçoit les paramètres suivants :
• Hauteur de la zone de dégradé : hauteur (en pixels) sur laquelle s’étend le dégradé • Rotation de la zone de dégradé : rotation (en radians) qui sera appliquée au dégradé • Translation horizontale : distance (en pixels) de déplacement horizontal du dégradé • Translation verticale : distance (en pixels) de déplacement vertical du dégradé Par exemple, supposons un dégradé possédant les caractéristiques suivantes :
Ce code trace trois dégradés avec le même style de remplissage, spécifié avec une distribution égale de rouge, vert et bleu. Les dégradés sont tracés à l’aide de la méthode drawRect() avec des largeurs en pixels de 50, 100 et 150 respectivement. La matrice de dégradé qui est spécifiée dans la méthode beginGradientFill() est créée avec une largeur de 100 pixels. Le premier dégradé ne couvre donc que la moitié de son spectre, le deuxième le couvre en entier, et le troisième le couvre en entier et possède 50 pixels supplémentaires de bleu à droite.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Un objet Graphics trace des cercles et des carrés, mais il permet aussi de dessiner des formes plus complexes, en particulier lorsque les méthodes de dessin sont utilisées en combinaison avec les propriétés et les méthodes de la classe Math. La classe Math contient des constantes d’intérêt général en mathématiques, telles que Math.PI (environ 3,14159265...), qui est la constante définissant le rapport entre la circonférence et le diamètre d’un cercle. Elle contient également des méthodes de fonctions trigonométriques, entre autres Math.sin(), Math.cos() et Math.tan(). L’utilisation de ces méthodes et constantes pour le dessin de formes permet d’obtenir des effets visuels plus dynamiques, en particulier en utilisant des répétitions et des récursions. De nombreuses méthodes de la classe Math attendent des mesures circulaires en radians, et non en degrés. La conversion entre ces deux types d’unités représente elle-même un cas d’utilisation courante de la classe Math : var degrees = 121; var radians = degrees * Math.PI / 180; trace(radians) // 2.111848394913139
Math.sin() et Math.cos() pour une même valeur. var var var var var var
L’un des avantages de la création de contenu graphique avec l’API de dessin est que ce contenu peut être repositionné à loisir. Tout ce que vous tracez peut être modifié, en modifiant simplement les variables utilisées pour ce dessin. Vous pouvez donc obtenir de l’animation en changeant les variables et en retraçant, soit sur un nombre d’images donné, soit à l’aide d’un timer. Par exemple, le code suivant change l’affichage à chaque nouvelle image (en écoutant l’événement Event.ENTER_FRAME) : il incrémente la valeur de degrés actuelle, puis ordonne à l’objet graphique d’effacer et redessiner avec la nouvelle position. stage.frameRate = 31; var currentDegrees:Number = 0; var radius:Number = 40; var satelliteRadius:Number = 6; var container:Sprite = new Sprite(); container.x = stage.stageWidth / 2; container.y = stage.stageHeight / 2; addChild(container); var satellite:Shape = new Shape(); container.addChild(satellite); addEventListener(Event.ENTER_FRAME, doEveryFrame); function doEveryFrame(event:Event):void { currentDegrees += 4; var radians:Number = getRadians(currentDegrees); var posX:Number = Math.sin(radians) * radius; var posY:Number = Math.cos(radians) * radius; satellite.graphics.clear(); satellite.graphics.beginFill(0); satellite.graphics.drawCircle(posX, posY, satelliteRadius); } function getRadians(degrees:Number):Number Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’exemple de générateur algorithmique d’effets visuels trace de manière dynamique plusieurs « satellites », des cercles qui se déplacent suivant une orbite circulaire. Les fonctionnalités présentées sont les suivantes :
• Utilisation de l’interaction de l’utilisateur pour modifier les propriétés utilisées pour le dessin • Effet d’animation par effacement du contenu et retraçage à chaque nouvelle image. L’exemple de la section précédente animait un satellite isolé à l’aide de l’événement Event.ENTER_FRAME. Cet exemple le reprend en y ajoutant un panneau de contrôle avec divers curseurs qui actualisent immédiatement l’affichage de plusieurs satellites. Dans cet exemple, le code est formalisé dans des classes externes et le code de création du satellite est imbriqué dans une boucle, en conservant une référence à chaque satellite dans le tableau satellites. Pour obtenir les fichiers d’application de cet exemple, voir www.adobe.com/go/learn_programmingAS3samples_flash_fr. Les fichiers de l’application se trouvent dans le dossier Samples/AlgorithmicVisualGenerator. Celui-ci contient les fichiers suivants : Fichier
L’application commence par créer trois écouteurs. Le premier attend qu’un événement soit distribué par le panneau de contrôle pour signaler qu’une reconstruction des satellites est nécessaire. Le second attend des changements de taille de la scène du fichier SWF. Le troisième attend le passage de chaque image du fichier SWF et son retraçage à l’aide de la fonction doEveryFrame().
Utilisation de l’API de dessin
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Après la définition de ces écouteurs, la fonction build() est appelée. Cette fonction appelle d’abord la fonction clear(), qui efface le contenu du tableau satellites et supprime les éventuelles formes déjà présentes sur la scène. Cette précaution est nécessaire car la fonction build() peut être appelée à nouveau à la suite d’un événement diffusé par le panneau de contrôle, par exemple en cas de modification des couleurs. Dans ce cas, les satellites doivent être supprimés et recréés. La fonction crée ensuite les satellites, en définissant les propriétés initiales nécessaires à cette création, dont la variable position qui définit une position aléatoire sur l’orbite et la variable color, qui dans cet exemple ne change pas une fois que le satellite a été créé. Lors de la création de chaque satellite, une référence est ajoutée dans le tableau satellites. Lorsque la fonction doEveryFrame() est appelée, elle actualise tous les satellites du tableau.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La fonction doEveryFrame() est au cœur du processus d’animation de l’application. Elle est appelée à chaque image, donc à une fréquence identique à la cadence du fichier SWF. Les variables du dessin changent légèrement, ce qui permet d’obtenir un effet d’animation. La fonction efface d’abord tous les éventuels dessins antérieurs et retrace l’arrière-plan. Elle effectue ensuite une boucle dans le conteneur de chaque satellite et incrémente la propriété position de chaque satellite, puis actualise les propriétés radius et orbitRadius qui peuvent avoir été modifiées par suite d’une action de l’utilisateur dans le panneau de contrôle. Enfin, la nouvelle position de chaque satellite est affichée en appelant la méthode draw() de la classe Satellite. Notez que la variable de compteur i n’est incrémentée que jusqu’à la valeur de la variable visibleSatellites. En effet, si l’utilisateur a limité à l’aide du panneau de contrôle le nombre de satellites affichés, les autres satellites de la boucle ne doivent pas être redessinés, mais masqués. La boucle chargée de cette action suit immédiatement celle qui est responsable du dessin. Lorsque la fonction doEveryFrame() se termine, le nombre de satellites visibles (visibleSatellites) est redessiné aux nouvelles positions.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’interactivité est assurée par le panneau de contrôle, qui est géré par la classe ControlPanel. Cette classe définit pour chaque curseur un écouteur et des valeurs individuelles minimum, maximum et par défaut. Lorsque l’utilisateur déplace ces curseurs, la fonction changeSetting() est appelée. Elle actualise les propriétés du panneau de contrôle. Si la modification nécessite un nouvel affichage, un événement est distribué et pris en charge dans le fichier principal de l’application. En fonction de la modification signalée par le panneau de contrôle, la fonction doEveryFrame() redessine chaque satellite sur la base des nouvelles variables.
• Les satellites pourraient utiliser une détection de collision entre eux. L’API de dessin peut être considérée comme autre solution pour la création d’effets visuels dans l’environnement de création Flash, en dessinant des formes de base lors de l’exécution. Mais elle permet aussi de créer des effets visuels qu’il serait impossible de créer manuellement. L’API de dessin et quelques notions de mathématiques permettent au développeur en ActionScript de donner vie à de nombreuses créations inattendues.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures Flash Player 10, Adobe AIR 1.5 et les moteurs d’exécution Flash ultérieurs prennent en charge un jeu avancé de fonctions de dessin. Les améliorations de l’API de dessin associées à ces moteurs d’exécution, qui étendent les méthodes de dessin des versions antérieures, vous permettent de définir des ensembles de données pour générer des formes, les modifier lors de l’exécution et créer des effets tridimensionnels. Les améliorations de l’API de dessin consolident les méthodes existantes comme commandes alternatives. Ces commandes s’appuient sur des tableaux de vecteurs et des classes d’énumération pour fournir des ensembles de données aux méthodes de dessin. Les tableaux de vecteurs accélèrent le rendu de formes plus complexes. Les développeurs peuvent modifier les valeurs des tableaux par programmation pour rendre des formes dynamiques à l’exécution. Les nouvelles fonctions de dessins de Flash Player 10 sont décrites dans les sections suivantes : « Tracés de dessin » à la page 244, « Définition des règles d’enroulement » à la page 245, « Utilisation des classes de données graphiques » à la page 247 et « A propos de l’utilisation de drawTriangles() » à la page 250. Vous souhaiterez probablement effectuer les tâches suivantes à l’aide des fonctions avancées de l’API de dessin dans ActionScript :
• Définition de tracés pour tracer des formes par programmation en une seule opération • Définition de règles d’enroulement pour déterminer le remplissage de formes se chevauchant • La lecture du contenu graphique vectoriel d’un objet d’affichage, par exemple pour sérialiser et enregistrer les données graphiques, pour générer une feuille Sprite à l’exécution ou pour dessiner une copie du contenu graphique vectoriel.
La liste de référence suivante énumère les termes importants que vous rencontrerez dans cette section :
Pour plus d’informations sur les objets Vector, voir « Tableaux indexés » à la page 27.
Tracés de dessin Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures La section sur le dessin de lignes et de courbes (voir « Dessin de lignes et de courbes » à la page 231) a présenté les commandes permettant de tracer une ligne (Graphics.lineTo()) ou courbe (Graphics.curveTo()) unique, puis de la déplacer vers un autre point (Graphics.moveTo()) pour obtenir une forme. Les méthodes Graphics.drawPath() et Graphics.drawTriangles() acceptent une série d’objets représentant ces mêmes commandes de dessin comme paramètre. Ces méthodes permettent de définir une série de commandes Graphics.lineTo(), Graphics.curveTo() ou Graphics.moveTo() traitées par le moteur d’exécution Flash en une seule instruction. La classe d’énumération GraphicsPathCommand définit une série de constantes qui correspondent aux commandes de dessin. Vous transmettez une série de ces constantes (encapsulées dans une occurrence de Vector) comme paramètre de la méthode Graphics.drawPath(). Vous pouvez ensuite rendre une forme entière ou plusieurs formes à l’aide d’une seule commande. Vous pouvez aussi modifier les valeurs transmises à ces méthodes pour modifier une forme existante. Outre l’occurrence Vector des commandes de dessin, la méthode drawPath() a besoin d’un ensemble de coordonnées qui correspondent aux coordonnées de chaque commande de dessin. Créez une occurrence de Vector contenant des coordonnées (instances de Number) et transmettez-la à la méthode drawPath() comme second argument (data). Remarque : les valeurs du vecteur ne sont pas des objets Point. Le vecteur est une série de nombres, dont chaque paire représente une paire de coordonnées x/y. La méthode Graphics.drawPath() fait correspondre chaque commande à ses valeurs de point respectives (une série de deux ou quatre nombres) pour générer un tracé dans l’objet Graphics :
Règle d’enroulement standard, la règle pair-impair est utilisée par l’API de dessin héritée. C’est aussi la règle par défaut de la méthode Graphics.drawPath(). Lorsqu’elle est appliquée, des tracés qui se croisent alternent entre des remplissages ouverts et fermés. Si deux carrés utilisant un même remplissage se croisent, la zone d’intersection est remplie. En règle générale, les zones adjacentes ne sont pas remplies ou leur remplissage n’est pas effacé. La règle non null, en revanche, se fonde sur l’enroulement (direction du tracé) pour déterminer si les zones définies par des tracés qui se croisent sont remplies. Lorsque des tracés dont l’enroulement est différent se croisent, la zone définie n’est pas remplie, comme avec la règle pair-impair. Si l’enroulement est identique, la zone dont le remplissage serait effacé est remplie :
Dernière mise à jour le 27/4/2013
L’API de dessin amélioré inclut un ensemble de classes dans le package flash.display qui met en œuvre l’interface IGraphicsData. Ces classes fonctionnent comme des objets de valeur (conteneurs de données) qui représentent les méthodes de l’API de dessin. Les classes suivantes implémentent l’interface IGraphicsData :
• GraphicsEndFill Vous remarquerez qu’il existe plusieurs classes de remplissage (Fill) correspondant à chaque style de remplissage, mais une seule classe de trait (Stroke). ActionScript propose une seule classe de trait IGraphicsData car elle définit son style sur la base des classes de remplissage. Ainsi, chaque trait est en fait défini par une combinaison de la classe stroke et d’une classe fill. Pour le reste, l’API de ces classes de données graphiques est identique aux méthodes qu’elles représentent dans la classe flash.display.Graphics : Méthode graphique
GraphicsPath.wideMoveTo()) pour simplifier la définition de ces commandes pour une occurrence de GraphicsPath. Ces méthodes facilitent la définition ou la mise à jour directe des commandes et des valeurs de données.
Lorsque vous disposez d’une série d’instances de IGraphicsData, utilisez la méthode drawGraphicsData() de la classe Graphics pour effectuer le rendu des graphiques. La méthode drawGraphicsData() exécute un ensemble d’instructions de dessin à partir d’un vecteur d’instances de IGraphicsData en séquence :
IGraphicsData pour tracer un ensemble enregistré de tracés, et inversement. Remarque : la méthode Graphics.clear() permet d’effacer un dessin avant d’en commencer un nouveau, à moins que vous ne complétiez le dessin d’origine, comme l’illustre l’exemple ci-dessus. Lorsque vous modifiez une partie d’un tracé ou d’un ensemble d’objets IGraphicsData, retracez le dessin entier pour visualiser les changements. Lorsque vous utilisez des classes de données graphiques, le remplissage est rendu chaque fois que trois points au moins sont tracés car la forme est nécessairement fermée à ce point. Bien que le remplissage ait un effet de fermeture, ce n’est pas le cas du trait. Ce comportement est différent de celui de commandes Graphics.lineTo() ou Graphics.moveTo() utilisées plusieurs fois.
Dans Flash Player 11.6, Adobe AIR 3.6 et versions ultérieures, vous pouvez utiliser la méthode readGraphicsData() de la classe Graphics non seulement pour tracer le contenu vectoriel d’un objet d’affichage, mais aussi pour obtenir une représentation en données du contenu graphique vectoriel de cet objet. Ceci peut être utilisé pour créer un instantané d’un graphique afin notamment d’enregistrer, de copier ou de créer une feuille Sprite lors de l’exécution. L’appel de la méthode readGraphicsData() renvoie une occurrence de Vector contenant des objets IGraphicsData. Il s’agit des mêmes objets que ceux utilisés pour tracer des graphiques vectoriels à l’aide de la méthode drawGraphicsData(). Plusieurs limitations s’appliquent à la lecture des graphiques vectoriels avec la méthode readGraphicsData(). Pour plus d’informations, voir l’entrée readGraphicsData() dans le Guide de référence ActionScript.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures Une autre méthode avancée intégrée à Flash Player 10 et Adobe AIR 1.5, Graphics.drawTriangles(), s’apparente à la méthode Graphics.drawPath(). La méthode Graphics.drawTriangles() utilise également un objet Vector.<Number> pour spécifier les points permettant de dessiner un tracé. La méthode Graphics.drawTriangles() a néanmoins pour but principal de faciliter la création d’effets tridimensionnels par le biais d’ActionScript. Pour plus d’informations sur l’utilisation de Graphics.drawTriangles() pour produire des effets tridimensionnels, voir « Création d’effets 3D à l’aide de triangles » à la page 375.
(lignes, courbes et polygones) générées à l’aide de formules mathématiques. Les images bitmap sont définies par la largeur et la hauteur de l’image, mesurées en pixels, et par le nombre de bits contenu dans chaque pixel (ce nombre de bits définit le nombre de couleurs que peut comporter l’image). Dans le cas d’une image bitmap utilisant le modèle colorimétrique RVB, les pixels sont composés de trois octets : rouge, vert et bleu. Chaque octet contient une valeur comprise entre 0 et 255. C’est la combinaison de ces octets pour chaque pixel qui produit une couleur, un peu comme le mélange des couleurs de base par un peintre. Par exemple, un pixel contenant les valeurs 255, 102 et 0 respectivement pour les octets dévolus au rouge, au vert et au bleu produira un orange vif. La qualité d’une image bitmap est déterminée en combinant la résolution en pixels de l’image avec sa profondeur de couleur exprimée en bits ou en octets. La résolution définit le nombre de pixels contenus dans l’image. Plus le nombre de pixels est important, plus la résolution est élevée et plus l’image semble bien définie. La profondeur de couleurs définit la quantité d’informations colorimétriques contenues par chaque pixel. Par exemple, une image ayant une profondeur de couleur de 16 bits par pixel ne peut pas représenter un nombre de nuances aussi élevé qu’une image ayant une profondeur de couleur de 48 bits. En conséquence, l’image sur 48 bits aura plus de nuances que la version sur 16 bits. Dans la mesure où les images bitmap dépendent de la résolution, il est délicat de modifier leur échelle, ce qui se remarque particulièrement avec les images bitmap agrandies, qui perdent beaucoup de détails et de qualité.
Utilisation des images bitmap
Les images bitmap existent en divers formats de fichier. Ces formats utilisent différents types d’algorithmes de compression pour réduire la taille des fichiers et optimiser la qualité de l’image en fonction de sa destination. Les moteurs d’exécution Adobe gèrent les formats d’image bitmap BMP, GIF, JPG, PNG et TIFF. BMP Le format BMP (pixellisé) est un format d’image par défaut utilisé par le système d’exploitation Microsoft Windows. Il ne fait appel à aucune forme d’algorithme de compression ; il en résulte généralement des tailles de fichiers assez importantes. GIF Le format GIF (Graphics Interchange Format) fut développé à l’origine par CompuServe en 1987, dans le but de transmettre des images en 256 couleurs (codées sur 8 bits). Ce format, qui permet d’obtenir des fichiers de petite taille, est très utilisé pour les images sur le Web. Toutefois, en raison de son nombre limité de couleurs, ce format n’est pas adapté aux photographies, qui nécessitent en général un nombre de nuances plus élevé. Les images GIF autorisent la transparence sur un bit, ce qui permet de rendre les couleurs invisibles (ou transparentes). C’est ainsi que sont produits les fonds transparents des images de pages Web. JPEG Développé par le Joint Photographic Experts Group (JPEG), le format d’image JPEG (souvent noté JPG) fait appel à un algorithme de compression avec perte pour autoriser une profondeur de couleur de 24 bits avec une taille de fichier très réduite. En raison de la compression avec perte, chaque fois que l’image est enregistrée elle perd des données, donc de la qualité, mais la taille de fichier résultante en est d’autant plus réduite. Le format JPEG est idéal pour les photographies, car il permet d’afficher des millions de couleurs différentes. La possibilité de contrôler le taux de compression appliqué à l’image permet de modifier la qualité de l’image et la taille du fichier. PNG Le format PNG (Portable Network Graphics) a été créé comme autre possibilité gratuite (open source) au format de fichier GIF, qui est breveté. Les fichiers PNG acceptent jusqu’à 64 bits de profondeur de couleur, ce qui permet d’obtenir jusqu’à 16 millions de couleurs. Le format PNG étant relativement récent, les versions anciennes de certains navigateurs ne gèrent pas ces fichiers. Contrairement au JPG, le format PNG utilise une compression sans perte, ce qui signifie qu’aucune donnée de l’image n’est perdue lors de l’enregistrement. De plus, les fichiers PNG acceptent également la transparence alpha, ce qui autorise jusqu’à 256 niveaux de transparence. TIFF Le format TIFF (ou Tagged Image File Format) était le format multiplate-forme de choix avant l’arrivée de PNG. Le format TIFF a un inconvénient qui est la multiplicité de ses variétés : aucun lecteur n’est en mesure de traiter toutes les versions disponibles. De surcroît, les navigateurs Web ne prennent pas en charge ce format actuellement. TIFF peut utiliser une compression avec ou sans pertes et il est en mesure de traiter des espaces de couleurs spécifiques au périphérique tels que CMJN (cyan-magenta-jaune-noir). Fichiers bitmap transparents et opaques Les images bitmap qui utilisent le format GIF ou PNG peuvent comporter pour chaque pixel un octet supplémentaire pour le canal alpha. Cet octet de pixel supplémentaire représente la valeur de transparence du pixel. Les images GIF n’autorisent la transparence que sur la base d’un bit, ce qui ne permet de spécifier la transparence que pour une seule couleur (dans une palette de 256 couleurs). Par contre, les images PNG acceptent jusqu’à 256 niveaux de transparence. Cette caractéristique est particulièrement intéressante pour « fondre » les images ou le texte avec l’arrière-plan.
La liste suivante contient des termes importants relatifs aux graphiques bitmap : Alpha Niveau de transparence (ou, plus précisément, d’opacité) d’une couleur ou d’une image. La valeur alpha est fréquemment appelée valeur du canal alpha. Couleur ARGB Modèle colorimétrique suivant lequel la couleur de chaque pixel est définie selon ses composants rouge,
Canal de couleur En général, les couleurs sont représentées par le mélange des couleurs primaires, rouge, vert et bleu (pour les graphiques sur ordinateur). Chaque couleur primaire est considérée comme un canal de couleur. C’est le mélange des proportions de chaque canal de couleur qui détermine la couleur finale. Codage des couleurs Parfois appelée codage, cette caractéristique détermine la quantité de mémoire vive dévolue à
Pixel Unité d’information de base d’une image bitmap (fondamentalement, un point coloré). Résolution Dimensions d’une image en pixels, qui détermine le niveau de détails fins d’une image. La résolution est
Couleur RVB Modèle colorimétrique suivant lequel la couleur de chaque pixel est définie selon ses composants rouge,
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les principales classes ActionScript 3.0 d’utilisation des images bitmap sont la classe Bitmap, qui permet d’afficher les images bitmap à l’écran, et la classe BitmapData, qui permet d’accéder et de manipuler les données brutes d’une image bitmap.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Sous-classe de la classe DisplayObject, la classe Bitmap est la principale classe utilisée en ActionScript 3.0 pour l’affichage d’images bitmap. Ces images sont souvent chargées par le biais de la classe flash.display.Loader ou créées dynamiquement à l’aide du constructeur Bitmap(). En cas de chargement d’une image provenant d’une source externe, un objet Bitmap ne peut contenir que des images aux formats GIF, JPEG ou PNG. L’occurrence de l’objet Bitmap peut être considérée comme enveloppe d’un objet BitmapData devant être affiché sur la scène. Une occurrence de Bitmap étant un objet d’affichage, toutes les caractéristiques et fonctionnalités des objets d’affichage peuvent être utilisées pour la manipuler. Pour plus d’informations sur l’utilisation des objets d’affichage, voir « Programmation de l’affichage » à la page 156.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Outre les fonctionnalités communes à tous les objets d’affichage, la classe Bitmap dispose de quelques fonctionnalités supplémentaires, propres aux images bitmap. La propriété pixelSnapping de la classe Bitmap détermine si un objet Bitmap accroche le pixel le plus proche. Cette propriété accepte l’une des trois constantes définies dans la classe PixelSnapping : ALWAYS, AUTO et NEVER. La syntaxe de l’accrochage aux pixels est la suivante : myBitmap.pixelSnapping = PixelSnapping.ALWAYS;
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe BitmapData, qui se trouve dans le package flash.display, peut être comparée à un cliché photographique des pixels d’une image bitmap, que celle-ci soit chargée ou créée dynamiquement. Ce cliché est représenté par une grille de données des pixels de l’objet. La classe BitmapData contient également une série de méthodes permettant de créer et modifier des données de pixels. Pour instancier un objet BitmapData, utilisez le code suivant : var myBitmap:BitmapData = new BitmapData(width:Number, height:Number, transparent:Boolean, fillColor:uinit);
Dans AIR 1.5 et Flash Player 10, la taille maximale d’un objet BitmapData est de 8 191 pixels en largeur ou en hauteur, et le nombre total de pixels ne peut pas excéder 16 777 215 pixels (ainsi, si la largeur d’un objet BitmapData est de 8 191 pixels, sa hauteur maximale doit être de 2 048 pixels). Dans Flash Player 9 et les versions antérieures, ainsi que dans AIR 1.1 et les versions antérieures, la limite est de 2 880 pixels de haut sur 2 880 pixels de large. Le paramètre transparent indique si l’image bitmap comporte un canal alpha (true) ou non (false). Le paramètre fillColor est une valeur colorimétrique sur 32 bits qui spécifie la couleur d’arrière-plan, ainsi que la valeur de la
Bitmap à la liste d’affichage en appelant la méthode addChild() ou addChildAt() du conteneur d’objet d’affichage qui contiendra cette occurrence de Bitmap. Pour plus d’informations sur l’utilisation de la liste d’affichage, voir « Ajout d’objets d’affichage à la liste d’affichage » à la page 165. L’exemple suivant crée un objet BitmapData avec un remplissage rouge, et l’affiche dans une occurrence de Bitmap :
La classe BitmapData contient des méthodes qui permettent de modifier les valeurs des données de pixels.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour modifier une image bitmap au niveau des pixels, il est d’abord nécessaire d’obtenir les valeurs colorimétriques des pixels de la zone à modifier. La méthode getPixel() permet d’obtenir ces valeurs de pixels. La méthode getPixel() renvoie les valeurs RVB des coordonnées (de pixels) x et y qui lui sont passées en paramètres. Si l’un des pixels comporte des informations de transparence (canal alpha), il est nécessaire d’utiliser la méthode getPixel32(). Cette méthode récupère également une valeur RVB, mais contrairement à ce qui se passe avec getPixel(), la valeur renvoyée par getPixel32() contient des données supplémentaires qui représentent la valeur du canal alpha (transparence) du pixel sélectionné. Pour simplement modifier la couleur ou la transparence d’un pixel contenu dans un bitmap, il est aussi possible d’utiliser la méthode setPixel() ou setPixel32(). Pour définir la couleur d’un pixel, il suffit de passer les coordonnées x et y et la valeur colorimétrique à l’une de ces méthodes. Dans l’exemple suivant, setPixel() est utilisée pour tracer une croix sur un fond vert BitmapData. La méthode getPixel() permet ensuite de récupérer la valeur colorimétrique du pixel ayant les coordonnées 50, 50 et de suivre la valeur renvoyée. import flash.display.Bitmap; import flash.display.BitmapData; var myBitmapData:BitmapData = new BitmapData(100, 100, false, 0x009900); for (var i:uint = 0; i < 100; i++) { var red:uint = 0xFF0000; myBitmapData.setPixel(50, i, red); myBitmapData.setPixel(i, 50, red); } var myBitmapImage:Bitmap = new Bitmap(myBitmapData); addChild(myBitmapImage); var pixelValue:uint = myBitmapData.getPixel(50, 50); trace(pixelValue.toString(16));
élément du tableau d’octets (autrement dit, les valeurs des pixels) est un entier non signé (valeurs non multipliées sur 32 bits).
Au fur et à mesure de la lecture (ou de l’écriture) des données dans inputByteArray, la méthode ByteArray.readUnsignedInt() est appelée pour chaque pixel du tableau. Si pour une raison quelconque inputByteArray ne contient pas un rectangle complet de données de pixels, la méthode interrompt le traitement des données de l’image.
L’exemple suivant utilise les méthodes getPixels() et setPixels() pour copier un groupe de pixels d’un objet BitmapData à un autre : import import import import
La méthode BitmapData.hitTest() accepte cinq paramètres :
Flash Player 11.3 et les versions ultérieures et dans AIR 3.3 et les versions ultérieures).
BitmapData à un autre. Cette méthode renvoie un nouvel objet BitmapData qui est un clone exact de l’occurrence originale. L’exemple suivant clone une copie d’un carré orange (parent) et place le clone à côté du carré parent original : import flash.display.Bitmap; import flash.display.BitmapData; var myParentSquareBitmap:BitmapData = new BitmapData(100, 100, false, 0x00ff3300); var myClonedChild:BitmapData = myParentSquareBitmap.clone(); var myParentSquareContainer:Bitmap = new Bitmap(myParentSquareBitmap); this.addChild(myParentSquareContainer); var myClonedChildContainer:Bitmap = new Bitmap(myClonedChild); this.addChild(myClonedChildContainer); myClonedChildContainer.x = 110;
Cette méthode prend un « cliché » rectangulaire (défini par le paramètre sourceRect) de l’image source et le copie dans une autre zone rectangulaire de taille égale. L’emplacement du rectangle ainsi « collé » est défini par le paramètre destPoint. La méthode copyChannel() analyse une valeur de canal de couleur prédéfini (alpha, rouge, vert ou bleu) dans un objet source BitmapData et la copie dans un canal donné de l’objet BitmapData de destination. Cette méthode n’affecte pas les autres canaux de l’objet BitmapData de destination. Les méthodes draw() et drawWithQuality() dessinent ou affichent le contenu graphique d’un objet d’affichage source (Sprite, Clip, etc.) dans un nouveau bitmap. Les paramètres matrix, colorTransform, blendMode et clipRect permettent de modifier l’aspect du nouveau bitmap. Cette méthode utilise le programme de rendu vectoriel de Flash Player et AIR pour générer les données. Pour appeler la méthode draw() ou drawWithQuality(), vous devez lui transmettre l’objet source (Sprite, Clip ou tout autre objet d’affichage) comme premier paramètre, comme ci-dessous : myBitmap.draw(movieClip);
Flash Player 11.3 et les versions ultérieures, AIR 3.3 et les versions ultérieures La méthode flash.display.BitmapData.encode() permet de compresser de façon native les données d’une image bitmap dans l’un des formats de compression d’image suivants :
Vous pouvez utiliser cette fonction pour le traitement des images dans le cadre d’un flux de chargement ou de téléchargement sur le serveur. L’exemple de fragment de code suivant compresse l’objet BitmapData avec JPEGEncoderOptions : // Compress a BitmapData object as a JPEG file. var bitmapData:BitmapData = new BitmapData(640,480,false,0x00FF00); var byteArray:ByteArray = new ByteArray(); bitmapData.encode(new Rectangle(0,0,640,480), new flash.display.JPEGEncoderOptions(), byteArray);
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour modifier l’aspect d’un bitmap, vous pouvez lui appliquer un effet de bruit à l’aide de la méthode noise() ou de la méthode perlinNoise(). La « neige » qui apparaît sur l’écran d’un téléviseur mal réglé est du bruit, ou du souffle. Pour appliquer un effet de bruit à un bitmap, utilisez la méthode noise(). Cette méthode applique une valeur colorimétrique aléatoire aux pixels de la zone spécifiée d’une image bitmap. Cette méthode accepte cinq paramètres :
L’exemple suivant crée une image bitmap et lui applique un motif de bruit bleu :
à base de bitmaps. Elle peut malgré tout consommer beaucoup de ressources processeur, ce qui risque de ralentir le contenu et de provoquer des actualisations d’écran plus lentes que la cadence nominale, en particulier sur les ordinateurs plus anciens. En effet, les algorithmes de cette méthode effectuent des calculs en virgule flottante. Cette méthode accepte neuf paramètres (les six premiers sont obligatoires) :
{ import import import import
Pour obtenir cette fonctionnalité, il est possible de réafficher une nouvelle image contenant le plan actualisé à chaque déplacement. Il est également possible de créer une grande image globale et d’utiliser la méthode scroll(). La méthode scroll() copie une image bitmap affichée et la colle à un nouvel emplacement, spécifié par les paramètres (x, y). S’il se trouve qu’une partie de l’image est située hors écran, l’effet obtenu est celui d’un défilement de l’image. Si cette fonction est combinée avec un timer (ou un événement enterFrame), l’image semble animée. L’exemple suivant reprend l’exemple précédent et génère une image bitmap de grande taille (dont les trois-quarts sont restitués hors scène). La méthode scroll() est alors appliquée. Grâce à un écouteur pour l’événement enterFrame, l’image est décalée d’un pixel en diagonale vers le bas. Cette méthode est appelée pour chaque nouvelle image. Les parties de l’image non affichées initialement apparaissent alors peu à peu sur la scène grâce à ce défilement.
Les mipmaps sont des images bitmap qui sont regroupées et associées à une texture dans le but d’améliorer la qualité et les performances d’affichage à l’exécution. Chaque image bitmap dans le mipmap est une version de l’image bitmap principale, mais à un niveau de détails réduit. Par exemple, vous pouvez disposer d’un mipmap qui inclut une image principale à une qualité optimale de 64 × 64 pixels. Les images de qualité inférieure dans le mipmap seront de 32 × 32, 16 × 16, 8 × 8, 4 × 4, 2 × 2 et de 1 × 1 pixels. La diffusion en continu de texture fait référence à la capacité de charger tout d’abord les images bitmap de qualité inférieure, puis d’afficher progressivement les images bitmap de qualité supérieure au fur et à mesure de leur chargement. Etant donné que les bitmaps de qualité inférieure sont de petites images, elles se chargent plus rapidement que l’image principale. Par conséquent, les utilisateurs de l’application peuvent afficher l’image dans une application avant le chargement de l’image bitmap principale de qualité supérieure. Flash Player 9.115.0 (et les versions ultérieures) et AIR implémentent cette technique (dite de mip-mapping), en créant des versions optimisées à diverses échelles de chaque bitmap (en partant de 50 %). Flash Player 11.3 et AIR 3.3 prennent en charge la diffusion en continu de textures via le paramètre streamingLevels des méthodes Context3D.createCubeTexture() et Context3D.createTexture(). La compression de texture permet d'enregistrer des images de texture au format compressé directement sur le GPU en vue d'économiser la mémoire GPU et la bande passante. En règle générale, les textures sont compressées hors ligne et téléchargées sur le GPU au format compressé. Néanmoins, Flash Player 11.4 et AIR 3.4 prennent en charge la compression de texture à l'exécution, utile dans certaines situations, notamment lors du rendu des textures dynamiques d'une illustration vectorielle. Pour utiliser la compression de texture à l'exécution, procédez comme suit :
Les mipmaps sont créées pour les types de bitmap suivants :
• Une image bitmap dans la bibliothèque d’un document Flash Professional. • Un objet BitmapData. • Une image bitmap affichée à l’aide de la fonction loadMovie() d’ActionScript 2.0. Les mipmaps ne sont pas appliqués aux objets filtrés ni aux clips dont les bitmaps sont en cache. En revanche, ils sont appliqués si un objet d’affichage filtré contient des transformations de bitmap, même si le bitmap se trouve dans un contenu masqué. Le mipmapping est exécuté automatiquement, mais les quelques conseils suivants vous permettront d’être certain que vos images bénéficient de cette optimisation :
• Pour les bitmaps, il n’est pas nécessaire de définir la propriété smoothing sur true, mais l’activation de cette propriété assure une amélioration visible de la qualité.
être réduit comme suit : 320 x 64 > 160 x 32 > 80 x 16 > 40 x 8 > 20 x 4 > 10 x 2 > 5 x 1). Pour les textures tridimensionnelles, utilisez des mipmaps dans lesquels la résolution de chaque image est une puissance de 2 (2^n). Par exemple, la résolution de l’image principale est de 1 024 x 1 024 pixels. Les images de qualité inférieure dans le mipmap seront à 512 x 512, 256 x 256, 128 x 128 jusqu’à 1 x 1 pixels pour un total de 11 images dans le mipmap. Notez que le mip-mapping ne gère pas un contenu de bitmap dont la largeur ou la hauteur est impaire.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’exemple de lune en rotation animée illustre les techniques d’utilisation des objets Bitmap et des données d’image bitmap (objets BitmapData). L’exemple crée une animation d’une lune sphérique en rotation et utilise comme données d’image brutes une image plane de la surface de la lune. Les techniques suivantes sont illustrées :
• Création d’une animation par copie répétée des pixels de différentes parties d’une image source • Création d’une image bitmap par définition de la valeur des pixels Pour obtenir les fichiers d’application de cet exemple, voir www.adobe.com/go/learn_programmingAS3samples_flash_fr. Les fichiers d’application de la lune en rotation animée résident dans le dossier Samples/SpinningMoon. L’application se compose des fichiers suivants :
La première tâche à exécuter dans cet exemple consiste à charger une image externe, une photographie de la surface de la lune. Le chargement est géré par deux méthodes de la classe MoonSphere : le constructeur MoonSphere(), qui lance le processus de chargement, et la méthode imageLoadComplete(), qui est appelée au terme du chargement de l’image externe. Le chargement d’une image externe est similaire à celui d’un fichier SWF externe : il est réalisé par une occurrence de la classe flash.display.Loader. Le code ci-après de la méthode MoonSphere() commence à charger l’image : var imageLoader:Loader = new Loader(); imageLoader.contentLoaderInfo.addEventListener(Event.COMPLETE, imageLoadComplete); imageLoader.load(new URLRequest("moonMap.png"));
L’occurrence de Loader n’envoie pas d’événements en rapport avec le contenu chargé. En revanche, sa propriété contentLoaderInfo contient une référence à l’objet LoaderInfo qui est associé au contenu chargé dans l’objet Loader (en l’occurrence, l’image externe). L’objet LoaderInfo génère des événements en rapport avec le déroulement et la fin du chargement du contenu externe, notamment l’événement complete (Event.COMPLETE) qui déclenche un appel à la méthode imageLoadComplete() au terme du chargement de l’image. S’il est essentiel de lancer le chargement de l’image externe, il est tout aussi important de savoir comment procéder au terme de cette opération. Comme l’illustre le code ci-dessus, la fonction imageLoadComplete() est appelée une fois l’image chargée. Cette fonction exécute diverses opérations sur les données chargées, comme indiqué ultérieurement. Cependant, pour utiliser les données d’image, elle doit pouvoir y accéder. Une image externe chargée par le biais d’un objet Loader devient une image Bitmap jointe en tant qu’objet d’affichage enfant de l’objet Loader. Dans ce cas, la méthode écouteur d’événement a accès à l’occurrence de Loader dans l’objet événement transmis en tant que paramètre à la méthode. Les premières lignes de la méthode imageLoadComplete() sont les suivantes : private function imageLoadComplete(event:Event):void { textureMap = event.target.content.bitmapData; ... } (event.target.content.bitmapData) et la stocke dans la variable d’occurrence de textureMap, qui est utilisée en tant que source des données d’image pour créer l’animation de la lune en rotation. Ce processus est décrit ci-après.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Une animation, dans sa définition la plus simple, est l’illusion d’un mouvement ou d’un changement, créée par la modification graduelle d’une image. Cet exemple a pour but de créer l’illusion d’une lune sphérique tournant sur son axe vertical. Cependant, pour les besoins de l’animation, vous pouvez ne pas tenir compte de l’aspect de distorsion sphérique de l’exemple. Examinez l’image chargée et utilisée comme source des données d’image de la lune :
Observez que l’image contient en fait deux copies juxtaposées de la photographie de la surface de la lune. Cette image représente l’image source dans laquelle des données ont été copiées plusieurs fois pour créer un effet de mouvement. La juxtaposition de deux copies de l’image facilite la création d’un effet de défilement continu. Examinons en détail le processus d’animation afin de mieux le comprendre. Le processus s’applique à deux objets ActionScript distincts. Le premier de ces objets est l’image source chargée qui, dans le code, est représentée par l’occurrence de BitmapData textureMap Comme nous l’avons vu, les données d’image sont insérées dans textureMap dès le chargement de l’image externe à l’aide de ce code : textureMap = event.target.content.bitmapData;
En l’occurrence, le cliché est un rectangle dont l’origine coïncide avec le coin supérieur gauche de textureMap (ce qu’indiquent les deux premiers paramètres de Rectangle() : 0, 0) et dont la largeur et la hauteur correspondent aux propriétés width et height de sphere.
Représenté visuellement, le code copie les pixels de textureMap mis en évidence ci-dessous et les colle sur sphere. Autrement dit le contenu BitmapData de sphere correspond à la partie de textureMap mise en évidence :
Une fois l’image source chargée et sphere créé, il ne reste plus à la méthode imageLoadComplete() qu’à définir l’animation. L’animation est pilotée par une occurrence de Timer, rotationTimer, créée et lancée par le code suivant : var rotationTimer:Timer = new Timer(15); rotationTimer.addEventListener(TimerEvent.TIMER, rotateMoon); rotationTimer.start();
(TimerEvent.TIMER) entraîne l’appel de la méthode rotateMoon(). Enfin, l’appel de la méthode start() du timer entraîne le démarrage de celui-ci. De par la définition de rotationTimer, Flash Player appelle la méthode rotateMoon() dans la classe MoonSphere environ toutes les 15 millisecondes, ce qui se traduit par l’animation de la lune. Le code source de la méthode rotateMoon() est le suivant :
droit de textureMap et ne trouvera plus de pixels à copier sur sphere :
{ sourceX = 0; } pixels du nouveau rectangle source sur sphere. Pour ce faire, nous reprenons le code qui a initialement rempli sphere (voir plus haut), à la différence près que, dans l’appel du constructeur new Rectangle(), le bord gauche du rectangle est placé à sourceX : sphere.bitmapData.copyPixels(textureMap, new Rectangle(sourceX, 0, sphere.width, sphere.height), new Point(0, 0));
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La lune est bien entendu sphérique , ce n’est pas un rectangle. La photographie rectangulaire de la surface lunaire, qui fait l’objet d’une animation constante, doit donc être convertie en sphère. Cette opération comprend deux étapes : un masque cache tout le contenu excepté une partie circulaire de la photographie et un filtre Mappage de déplacement déforme l’apparence de la photographie, lui donnant un aspect tridimensionnel.
équatoriales. Pour déformer l’apparence de la photographie et lui donner un aspect tridimensionnel, nous allons utiliser un filtre Mappage de déplacement. Ce type de filtre permet de déformer une image. En l’occurrence, nous allons déformer la photographie de la lune pour lui donner un aspect plus réaliste, en compressant horizontalement les parties supérieures et inférieures de l’image sans toucher à son milieu. En supposant que le filtre intervienne sur une partie carrée de la photographie, la compression du haut et du bas mais pas du milieu aura pour effet de convertir le carré en cercle. L’animation de cette image déformée a un effet secondaire : la distance en pixels parcourue par le milieu de l’image semble supérieure à celle couverte par les parties supérieure et inférieure, d’où l’impression que le cercle est en fait un objet tridimensionnel (une sphère). Le code suivant permet de créer un filtre Mappage de déplacement appelé displaceFilter : var displaceFilter:DisplacementMapFilter; displaceFilter = new DisplacementMapFilter(fisheyeLens, new Point(radius, 0), BitmapDataChannel.RED, BitmapDataChannel.GREEN, radius, 0);
Mappage de déplacement créé, il est appliqué à sphere, toujours dans la méthode imageLoadComplete() : sphere.filters = [displaceFilter];
BitmapData serait une diapositive présentée par le biais du projecteur. Il est possible d’appliquer un filtre directement à un objet BitmapData, ce qui reviendrait à dessiner sur une diapositive pour modifier l’image. Vous pouvez aussi appliquer un filtre à tout objet d’affichage, y compris une occurrence de Bitmap, ce qui équivaudrait à placer un filtre devant l’objectif du projecteur pour déformer l’image à l’écran sans modifier la diapositive d’origine. Comme les données bitmap brutes sont accessibles par le biais de la propriété bitmapData d’une occurrence de Bitmap, rien n’empêche de leur appliquer directement le filtre. Dans ce cas, cependant, il est préférable d’appliquer directement le filtre à l’objet d’affichage Bitmap plutôt qu’aux données bitmap. Pour plus d’informations sur l’utilisation du filtre Mappage de déplacement en ActionScript, voir « Filtrage des objets d’affichage » à la page 276.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le fait qu’un filtre Mappage de déplacement implique en réalité deux images est un facteur important. L’image source est modifiée par le filtre. Dans cet exemple, il s’agit de l’occurrence de Bitmap sphere. L’autre image utilisée par le filtre est appelée l’image de mappage. Elle n’apparaît pas à l’écran. En revanche, la couleur de ses pixels est utilisée en entrée par la fonction de déplacement : la couleur d’un pixel se trouvant à des coordonnées x, y spécifiques détermine le déplacement (changement physique de position) à appliquer au pixel à ces coordonnées x, y dans l’image source. Dans cet exemple, pour utiliser le filtre Mappage de déplacement en vue de créer un effet sphérique, il est donc nécessaire d’utiliser l’image de mappage appropriée, c’est-à-dire une image au fond gris comportant un cercle rempli d’un dégradé d’une seule couleur (rouge) qui passe, horizontalement, du foncé au clair, comme illustré ci-dessous :
L’image de mappage, fisheyeLens, est créée par appel de la méthode createFisheyeMap() de la classe MoonSphere : var fisheyeLens:BitmapData = createFisheyeMap(radius);
{ var diameter:int = 2 * radius; var result:BitmapData = new BitmapData(diameter, diameter, false, BitmapData result créée sont égales au diamètre du cercle. En outre, cette occurrence n’a pas de transparence (le troisième paramètre correspond à false) et elle est pré-remplie par la couleur 0x808080 (gris moyen) : var result:BitmapData = new BitmapData(diameter, diameter, false, 0x808080);
{ for (var j:int = 0; j < diameter; j++) est divisée par le rayon pour obtenir un pourcentage de celui-ci plutôt qu’une distance absolue ((i - radius) / radius). Ce pourcentage est stocké dans une variable appelée pctX. La valeur équivalente sur l’axe y est calculée et
concerné se trouve sur le rayon du cercle). Si le pixel figure dans le cercle, une valeur colorimétrique calculée lui est affectée (voir la description à l’étape 4). Dans le cas contraire, ce pixel ne fait l’objet d’aucune manipulation et conserve la couleur par défaut, c’est-à-dire le gris moyen. if (pctDistance < 1) { ... Dernière mise à jour le 27/4/2013
Lorsque vous manipulez des images bitmap, vous pouvez décoder et charger ces dernières en mode asynchrone pour optimiser les performances perçues d’une application. Dans de nombreux cas, le décodage asynchrone d’une image bitmap prend autant de temps que le décodage synchrone. L’image bitmap est toutefois décodée dans un thread distinct avant que l’objet Loader associé n’envoie l’événement COMPLETE. Il est par conséquent possible de décoder en mode asynchrone des images de taille supérieure après leur chargement. La classe ImageDecodingPolicy du package flash.system permet de stipuler le modèle de chargement de bitmap. Le modèle de chargement par défaut est synchrone. Traitement du décodage de bitmap
10 MP). Si vous développez une application mobile AIR contenant des transitions de page, faites appel à ce traitement de chargement de bitmap pour optimiser les performances perçues de l’application.
Utilisation des images bitmap
Le code suivant illustre l’utilisation de la classe ImageDecodingPolicy : var loaderContext:LoaderContext = new LoaderContext(); loaderContext.imageDecodingPolicy = ImageDecodingPolicy.ON_LOAD var loader:Loader = new Loader(); loader.load(new URLRequest("http://www.adobe.com/myimage.png"), loaderContext);
Loader.loadBytes(). Néanmoins, toutes les autres méthodes qui prennent un objet LoaderContext comme argument ignorent toutes les valeurs ImageDecodingPolicy transmises. L’exemple suivant illustre la différence entre une image décodée en mode synchrone et en mode asynchrone : package { import import import import import import
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’une des façons de rendre une application plus séduisante est de lui ajouter des effets graphiques simples, comme une ombre portée derrière une photo pour créer l’illusion de la 3D, ou un rayonnement autour d’un bouton pour indiquer qu’il s’agit du bouton actif. ActionScript 3.0 comporte dix filtres qui peuvent être appliqués à n’importe quel objet d’affichage ou à une occurrence de BitmapData. Ces filtres vont des effets de base (filtres Ombre portée et Rayonnement) à des effets plus complexes, tels que le filtre Mappage du déplacement et le filtre Convolution matricielle. Remarque : outre les filtres intégrés, vous pouvez programmer des effets et filtres personnalisés par le biais de Pixel Bender (voir « Utilisation des shaders de Pixel Bender » à la page 310). Concepts importants et terminologie La liste de référence suivante contient des termes importants relatifs à la création de filtres : Biseau Effet de rebord créé en éclaircissant les pixels de deux côtés contigus et en assombrissant les pixels des deux
Convolution Distorsion des pixels d’une image obtenue en combinant la valeur de chaque pixel avec celle(s) d’un ou plusieurs des pixels voisins, selon divers pourcentages. Déplacement Décalage des pixels d’une image vers une nouvelle position. Matrice Grille de chiffres utilisée pour effectuer certains calculs mathématiques, en appliquant ces chiffres à diverses
Package flash.filters flash.display.DisplayObject.filters flash.display.BitmapData.applyFilter()
Les filtres permettent d’appliquer divers effets (ombre portée, biseau, flou, etc.) à des images bitmap et à des objets d’affichage. Chaque filtre étant défini sous forme de classe, il suffit pour appliquer un filtre de créer une occurrence d’un objet filtre, ce qui n’est guère différent de la création de tout autre objet. Après avoir créé une occurrence d’un objet filtre, il est facile de l’appliquer à un objet d’affichage à l’aide de la propriété filters de cet objet ou, dans le cas d’un objet BitmapData, de sa méthode applyFilter().
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour créer un objet filtre, il suffit d’appeler la fonction constructeur de la classe du filtre voulu. Par exemple, pour créer un objet DropShadowFilter, utilisez le code suivant : import flash.filters.DropShadowFilter; var myFilter:DropShadowFilter = new DropShadowFilter();
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lorsque l’objet filtre a été créé, vous pouvez l’appliquer à un objet d’affichage ou à un objet BitmapData, mais le mode d’application du filtre dépend de l’objet concerné. Application d’un filtre à un objet d’affichage Pour appliquer un effet de filtrage à un objet d’affichage, utilisez sa propriété filters. La propriété filters d’un objet d’affichage est une occurrence de l’objet Array, dont les éléments sont les objets filtres appliqués à l’objet d’affichage. Pour appliquer un seul filtre à un objet d’affichage, créez l’occurrence de ce filtre, ajoutez-la à une occurrence d’Array, et affectez cet objet Array à la propriété filters de l’objet d’affichage :
Le code précédent crée une occurrence d’Array en utilisant la syntaxe littérale d’Array (entre crochets), puis crée une nouvelle occurrence de BlurFilter comme élément du tableau, et affecte ce dernier à la propriété filters de l’objet d’affichage myDisplayObject.
Pour supprimer tous les filtres d’un objet d’affichage, il suffit d’affecter la valeur null à la propriété filters de celui-ci : myDisplayObject.filters = null;
Application d’un filtre à un objet BitmapData L’application d’un filtre à un objet BitmapData nécessite d’utiliser la méthode applyFilter() de l’objet BitmapData : var rect:Rectangle = new Rectangle(); var origin:Point = new Point(); myBitmapData.applyFilter(sourceBitmapData, rect, origin, new BlurFilter());
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le filtrage des objets d’affichage consiste à mettre en cache une copie de l’objet original sous forme d’un bitmap transparent. Lorsqu’un filtre a été appliqué à un objet d’affichage, le moteur d’exécution conserve en cache l’objet sous forme de bitmap tant que cet objet possède une liste de filtres valide. Le bitmap source est ensuite repris en tant qu’image originale pour les effets de filtrage suivants. Tout objet d’affichage comporte généralement deux bitmaps : le premier avec l’objet d’affichage source non filtré d’origine et un autre pour l’image finale après filtrage. L’image finale est utilisée pour le rendu. Tant que l’objet d’affichage ne change pas, l’image source ne nécessite aucune actualisation.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Plusieurs sources potentielles de confusion ou de problèmes peuvent survenir lors de l’utilisation de filtres. Filtres et mise en cache bitmap Pour appliquer un filtre à un objet d’affichage, vous devez activer la mise en cache sous forme de bitmap pour cet objet. Si vous appliquez un filtre à un objet d’affichage dont la propriété cacheAsBitmap est false, la propriété cacheAsBitmap de l’objet est automatiquement définie sur true. Si vous supprimez tous les filtres appliqués à l’objet d’affichage, la propriété cacheAsBitmap retrouve la valeur précédemment définie.
Si un ou plusieurs filtres sont déjà appliqués à un objet d’affichage, vous ne pouvez pas modifier le jeu de filtres en ajoutant d’autres filtres ou en supprimant des filtres existants du tableau de la propriété filters. Pour modifier le jeu de filtres appliqué ou lui ajouter des filtres, vous devez plutôt effectuer les modifications requises dans un tableau distinct, puis l’assigner à la propriété filters de l’objet d’affichage pour que les filtres soient appliqués à l’objet. La procédure la plus simple consiste à lire le tableau de la propriété filters dans une variable Array, puis à effectuer les modifications requises dans ce tableau temporaire. Vous réassignez alors ce tableau à la propriété filters de l’objet d’affichage. Dans les cas de figure plus complexes, il peut s’avérer nécessaire de conserver un tableau maître distinct de filtres. Vous effectuez toute modification requise dans ce tableau maître de filtres, puis vous le réassignez à la propriété filters de l’objet d’affichage après chaque modification. Ajout d’un autre filtre Le code suivant illustre le processus d’ajout d’un autre filtre à un objet d’affichage auquel sont déjà appliqués un ou plusieurs filtres. Initialement, un filtre Rayonnement est appliqué à l’objet d’affichage myDisplayObject. Lorsque l’utilisateur clique sur l’objet d’affichage, la fonction addFilters() est appelée. Dans cette fonction, deux filtres supplémentaires sont appliqués à myDisplayObject : import flash.events.MouseEvent; import flash.filters.*; myDisplayObject.filters = [new GlowFilter()]; function addFilters(event:MouseEvent):void { // Make a copy of the filters array. var filtersCopy:Array = myDisplayObject.filters; La technique la plus simple consiste à supprimer le filtre en tête de pile appliqué à l’objet (en d’autres termes, le dernier filtre appliqué à ce dernier). Vous utilisez la méthode pop() de la classe Array pour supprimer le filtre du tableau :
(première). Vous savez donc à l’avance quelle méthode Array utiliser (soit, dans ce cas, Array.pop() pour supprimer le filtre Ombre portée). Si le filtre à supprimer est toujours d’un type déterminé, mais qu’il n’occupe pas systématiquement la même position dans le jeu de filtres, vous pouvez vérifier le type de données de chaque filtre du tableau pour identifier le filtre à supprimer. Par exemple, le code suivant identifie le filtre Rayonnement dans un jeu de filtres et le supprime de ce dernier.
Rechercher et identifier le filtre approprié est similaire à l’approche précédente, excepté qu’au lieu d’effectuer une copie temporaire du tableau de filtres, la copie maîtresse est manipulée, puis appliquée à l’objet d’affichage.
Dernière mise à jour le 27/4/2013
Les zones filtrées (ombres portées, par exemple) situées hors du cadre de sélection d’un objet d’affichage ne sont pas prises en considération pour la détection de clics (chevauchement ou intersection de deux occurrences). La méthode de détection des clics de la classe DisplayObject étant de type vectoriel, il est impossible d’en pratiquer une sur le bitmap résultant. Par exemple, si vous appliquez un filtre Biseau à une occurrence de bouton, la détection des clics n’est pas possible sur la partie biseautée de l’occurrence. Le redimensionnement, la rotation et l’inclinaison ne sont pas pris en charge par les filtres ; si l’objet d’affichage filtré lui-même est redimensionné (scaleX et scaleY différents de 100 %), l’effet de filtre n’est pas redimensionné avec l’occurrence. La forme originale de l’occurrence est certes pivotée, inclinée ou redimensionnée, mais pas le filtre. Vous pouvez animer une occurrence avec un filtre afin de créer des effets réalistes, ou imbriquer des occurrences et utiliser la classe BitmapData pour animer des filtres afin d’obtenir ces effets. Filtres et objets bitmaps Si vous appliquez un filtre à un objet BitmapData, la propriété cacheAsBitmap de cet objet est automatiquement true. Le filtre peut ainsi être appliqué à la copie de l’objet plutôt qu’à ce dernier. Cette copie est alors placée à l’écran par-dessus l’objet original, aussi près que possible, au pixel près. Si les limites du bitmap original changent, la copie à laquelle le filtrage est appliqué est recréée à partir de l’original au lieu d’être étirée. Si vous supprimez tous les filtres de l’objet d’affichage, la propriété cacheAsBitmap retrouve sa valeur d’origine.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures ActionScript 3.0 comprend dix classes de filtre que vous pouvez appliquer aux objets d’affichage et aux objets BitmapData :
Flash Professional, vous pouvez utiliser son interface visuelle pour vérifier rapidement l’effet des différents filtres et de leurs réglages afin de créer l’effet désiré.
Convolution, filtre Mappage de déplacement et filtre Shader) permettent de créer des types d’effet beaucoup plus souples. Plutôt que proposer un effet unique optimisé, ils assurent puissance et souplesse. Par exemple, en choisissant différentes valeurs pour sa matrice, il est possible d’utiliser le filtre Convolution pour créer des effets de flou, de gravure, d’accentuation, mais aussi pour des transformations, la détection de contour des couleurs, etc. Chacun de ces filtres, qu’il soit simple ou complexe, dispose de propriétés dont les valeurs peuvent être modifiées. En général, il existe deux possibilités pour définir les propriétés d’un filtre. Tous les filtres permettent de définir leurs propriétés en passant des valeurs en paramètres au constructeur de l’objet filtre. Que les propriétés du filtre soient définies ou non par un passage de paramètres, il est aussi possible de modifier ultérieurement ses réglages en changeant les valeurs des propriétés de l’objet filtre. La plupart des exemples de code définissent directement les propriétés pour faciliter la compréhension de l’exemple. Néanmoins, il est également possible, en général, d’obtenir le même résultat avec moins de lignes de code, en passant les valeurs en paramètres dans le constructeur de l’objet filtre. Pour plus d’informations sur les caractéristiques de chaque filtre, ses propriétés et les paramètres constructeurs correspondants, voir les codes associés au package flash.filters dans le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe BevelFilter vous permet d’ajouter une bordure en relief à l’objet filtré. Avec ce filtre, les angles et les côtés des objets semblent ciselés, biseautés. Les propriétés de la classe BevelFilter permettent de modifier l’apparence du biseau. Vous pouvez définir les couleurs des zones claires et sombres, l’adoucissement et les angles des côtés du biseau, ainsi que la tille de ces derniers. Vous pouvez même créer un effet de poinçonnage. L’exemple suivant charge une image externe et lui applique un filtre Biseau.
Dernière mise à jour le 27/4/2013
Le filtre Ombre portée permet aussi d’appliquer des options de transformation au style de l’ombre portée (ombre interne ou externe, ou mode de masquage). Le code suivant crée un objet Sprite carré et lui applique un filtre Ombre portée.
Comme le filtre Ombre portée, le filtre Rayonnement possède des propriétés qui permettent de modifier la distance, l’angle et la couleur de la source lumineuse en fonction de l’effet désiré. L’objet GlowFilter comporte aussi plusieurs options pour modifier le style de rayonnement, notamment le rayonnement interne ou externe et le mode de masquage. Le code suivant crée un objet Sprite en forme de croix et lui applique un filtre Rayonnement.
L’exemple suivant crée un objet rectangle à l’aide de la méthode drawRect() de la classe Shape, puis lui applique un filtre Biseau dégradé :
L’exemple suivant dessine un cercle auquel un filtre Rayonnement dégradé est appliqué. Le montant de flou horizontal et vertical augmente à mesure que le pointeur de la souris s’approche du coin inférieur droit de la scène. Si l’utilisateur clique dans la scène, le niveau de flou augmente.
L’exemple de code suivant applique plusieurs filtres de base, en combinaison avec un timer pour la création d’actions répétitives, pour obtenir la simulation d’un feu de circulation. import import import import import import import import var var var var var var var var var var var var
La classe ColorMatrixFilter permet de manipuler les valeurs de couleur et les valeurs alpha des objets filtrés. Il est ainsi possible de créer des changements de saturation, des rotations de teinte (passage d’une palette d’une plage de couleur à une autre), de définir la luminance de la couche alpha et de produire d’autres effets de manipulation des couleurs en utilisant les valeurs d’un canal couleur pour les appliquer aux autres canaux. Le principe de fonctionnement de ce filtre est le suivant : les pixels de l’image source sont analysés un par un et leurs composants rouge, vert, bleu et alpha sont séparés. Les valeurs de la matrice de couleur sont alors multipliées par chacune de ces valeurs, et les résultats sont ajoutés pour déterminer la valeur colorimétrique résultante qui sera affichée à l’écran pour ce pixel. La propriété matrix du filtre est un tableau de 20 nombres qui sont utilisés pour le calcul de la couleur finale. Pour plus d’informations sur l’algorithme utilisé pour calculer les valeurs de couleur, voir la description de la propriété matrix de la classe ColorMatrixFilter dans le manuel Guide de référence ActionScript 3.0 pour la plateforme Adobe Flash.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe ConvolutionFilter permet d’appliquer un large éventail de transformations de traitement d’images aux objets BitmapData ou aux objets d’affichage, tels que la définition du flou, la détection du contour, l’accentuation, l’estampage et le biseautage. Le principe de fonctionnement du filtre Convolution est le suivant : les pixels de l’image source sont analysés un par un pour déterminer la couleur finale de ce pixel sur la base de sa valeur et de celles des pixels adjacents. Une matrice, sous forme d’un tableau de valeurs numériques, indique dans quelle mesure la valeur de chaque pixel adjacent particulier affecte la valeur finale. Le type de matrice le plus fréquemment utilisé est un tableau de trois par trois. La matrice comporte donc neuf valeurs :
Par exemple, la matrice suivante, appliquée à un filtre Convolution, laissera l’image intacte, exactement comme l’image originale :
// Load an image onto the Stage. var loader:Loader = new Loader(); var url:URLRequest = new URLRequest("http://www.helpexamples.com/flash/images/image1.jpg"); loader.load(url); this.addChild(loader); function applyFilter(event:MouseEvent):void { // Create the convolution matrix. var matrix:Array = [0, 0, 0, La classe DisplacementMapFilter utilise des valeurs de pixel extraites d’un objet BitmapData (appelé image de mappage du déplacement) pour appliquer un effet de déplacement à un nouvel objet. L’image de mappage du déplacement est en général différente de l’occurrence d’objet d’affichage ou BitmapData à laquelle le filtre est appliqué. L’effet de déplacement nécessite de déplacer les pixels de l’image filtrée, autrement dit de les décaler d’un certain niveau. Ce filtre permet de créer un effet de décalage, de gondole ou de marbrure. La direction et la valeur du déplacement appliqué à un pixel donné sont déterminées par la valeur colorimétrique de l’image de mappage du déplacement. Pour utiliser ce filtre, il est nécessaire de spécifier l’image de mappage, ainsi que les valeurs suivantes, qui permettent de contrôler le calcul du déplacement :
• Composant Y : canal couleur de l’image de mappage qui affecte la position y des pixels. • Echelle X : valeur multiplicatrice qui indique le niveau de déplacement sur l’axe x. • Echelle Y : valeur multiplicatrice qui indique le niveau de déplacement sur l’axe y. • Mode de filtrage : détermine la marche à suivre dans le cas d’espaces vides créés par le décalage des pixels. Les options, définies par des constantes dans la classe DisplacementMapFilterMode, sont d’afficher les pixels originaux (mode IGNORE), de décaler et transférer les pixels de l’autre côté de l’image (mode WRAP, qui est le mode par défaut), d’utiliser le pixel déplacé le plus proche (mode CLAMP) ou de remplir ces espaces vides avec une couleur (mode COLOR). Pour comprendre le fonctionnement d’un filtre de mappage de déplacement, prenons un exemple simple. Dans le code ci-dessous, une image est chargée, puis elle est centrée sur la scène et un filtre Mappage de déplacement lui est appliqué, ce qui déplace horizontalement (vers la gauche) les pixels de toute l’image.
• Point de mappage : cette valeur est définie pour le point 0, 0 (ici encore, le déplacement sera appliqué à toute l’image).
2 Il détermine la valeur du canal de couleur spécifié dans le pixel de mappage. Dans cet exemple, le canal de couleur
3 Ils comparent ensuite la valeur de déplacement à la valeur médiane (127, à mi-chemin entre 0 et 255). Si la valeur
(comme dans cet exemple), le pixel est déplacé dans une direction négative (vers la gauche pour l’axe x, vers le haut pour l’axe y). Plus précisément, le filtre soustrait la valeur de déplacement de 127, et le résultat (positif ou négatif) est la valeur relative de déplacement qui est appliquée. 4 Enfin, ils déterminent la valeur réelle de déplacement en calculant le pourcentage de déplacement complet
100 %. Ce pourcentage est ensuite multiplié par la valeur de l’échelle x ou de l’échelle y pour déterminer le nombre de pixels de déplacement à appliquer. Dans cet exemple, la valeur de déplacement est 100 % multiplié par un multiple de 250, soit environ 125 pixels à gauche. Comme nous ne spécifions aucune valeur pour les composants x et y, les valeurs par défaut (qui ne provoquent pas de déplacement) sont utilisées. C’est pourquoi l’image n’est pas déplacée dans le sens vertical. Dans cet exemple, le paramètre par défaut de mode de filtrage, WRAP, est utilisé, si bien que lorsque les pixels sont déplacés vers la gauche, l’espace laissé vide à droite est rempli par les pixels qui ont été décalés le long du côté gauche de l’image. Vous pouvez modifier cette valeur pour voir les différents effets ainsi obtenus. Par exemple, si vous ajoutez la ligne suivante dans la partie du code qui définit les propriétés de déplacement (avant la ligne loader.filters = [displacementMap]), l’image semble avoir subi un balayage : displacementMap.mode = DisplacementMapFilterMode.CLAMP;
Le cercle rouge est à l’origine du déplacement sur l’axe x (xyFilter.componentX = BitmapDataChannel.RED) et le cercle bleu est à l’origine du déplacement sur l’axe y (xyFilter.componentY = BitmapDataChannel.BLUE). Pour vous permettre de comprendre plus aisément l’aspect de l’image de mappage du déplacement, le code affiche les cercles originaux, ainsi que le cercle combiné qui fait office d’image de mappage, en bas de l’écran.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures La classe ShaderFilter vous permet d’utiliser un effet de filtre personnalisé défini en tant que shader de Pixel Bender. Parce que l’effet de filtre est écrit en tant que shader de Pixel Bender, il peut être entièrement personnalisé. Le contenu filtré est transmis au shader en tant qu’image d’entrée et le résultat de l’opération du shader devient le résultat du filtre. Remarque : le filtre Shader est pris en charge dans ActionScript à partir de Flash Player 10 et Adobe AIR 1.5. Pour appliquer un filtre Shader à un objet, vous devez commencer par créer une occurrence de Shader représentant le shader de Pixel Bender en cours d’utilisation. Pour plus d’informations concernant la procédure de création d’une occurrence de Shader et la définition d’une image d’entrée et des paramètres correspondants, voir « Utilisation des shaders de Pixel Bender » à la page 310. Lorsque vous utilisez un shader en tant que filtre, vous devez tenir compte de trois considérations importantes :
• Application de plusieurs filtres à un objet d’affichage Pour obtenir les fichiers d’application de cet exemple, voir www.adobe.com/go/learn_programmingAS3samples_flash_fr. Les fichiers d’application Filter Workbench résident dans le dossier Samples/FilterWorkbench. L’application se compose des fichiers suivants :
Dans le dossier com/example/programmingas3/filterWorkbench/ :
IFilterFactory. Chacune de ces classes permet de créer et de définir les valeurs associées à un type unique de filtre. Les panneaux de propriétés des filtres de l’application utilisent ces classes usine pour créer des occurrences des filtres correspondants, que la classe FilterWorkbenchController extrait et applique au contenu d’image.
BlurFactory.as Jeu de composants MXML qui assurent la fonctionnalité de chaque panneau utilisé pour définir les options d’un filtre unique.
Jeu de classes qui assurent la fonctionnalité de chaque panneau utilisé pour définir les options d’un filtre unique.
« BlurPanel » est lié à la classe définie dans BlurPanel.as). Les composants de l’interface utilisateur sont placés et identifiés par nom dans ces symboles.
ConvolutionPanel.as L’application Filter Workbench est conçue pour vous aider à expérimenter avec divers effets de filtre et générer le code ActionScript approprié correspondant. Elle vous permet de sélectionner trois fichiers distincts comportant un contenu visuel, tel que des images bitmap et une animation créée par Flash et d’appliquer huit filtres ActionScript distincts à l’image sélectionnée, soit seuls, soit combinés à d’autres filtres. L’application comprend les filtres suivants :
• Flou (flash.filters.BlurFilter) Dernière mise à jour le 27/4/2013
• Le filtre Convolution, qui n’est disponible qu’en ActionScript, comprend un jeu de valeurs de matrice de convolution couramment utilisées. Il est également possible de définir des valeurs personnalisées. Toutefois, bien que la classe ConvolutionFilter gère une matrice de n’importe quelle taille, l’application Filter Workbench utilise une matrice de 3 x 3 fixe, soit la taille de filtre la plus fréquemment utilisée.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’application Filter Workbench comprend un jeu de classes, une par filtre disponible, qui sont utilisées par les divers panneaux pour créer les filtres. Lorsqu’un utilisateur sélectionne un filtre, le code ActionScript associé au panneau de filtre crée une occurrence de la classe de filtres usine appropriée. (Ces classes portent le nom de classes usine, car elles ont pour objet de créer des occurrences d’autres objets, à l’instar d’une vraie usine qui fabrique des produits). Lorsque l’utilisateur modifie la valeur d’une propriété dans le panneau, le code correspondant appelle la méthode appropriée dans la classe usine. Chaque classe usine comporte des méthodes spécifiques utilisées par le panneau pour créer l’occurrence de filtre appropriée. Par exemple, si l’utilisateur sélectionne le filtre Flou, l’application crée une occurrence de BlurFactory. La classe BlurFactory comporte une méthode modifyFilter() qui gère trois paramètres : blurX, blurY et quality. Conjointement, ces paramètres permettent de créer l’occurrence de BlurFilter requise : private var _filter:BlurFilter; public function modifyFilter(blurX:Number = 4, blurY:Number = 4, quality:int = 1):void { _filter = new BlurFilter(blurX, blurY, quality); dispatchEvent(new Event(Event.CHANGE)); } La classe FilterWorkbenchController n’a pas besoin de connaître les détails précis de chaque classe usine associé au filtre. Elle doit juste savoir que le filtre a été modifié et être en mesure d’accéder à une copie de ce dernier. A cet effet, l’application comporte une interface, IFilterFactory, qui définit le comportement requis d’une classe usine de filtres pour que l’occurrence de FilterWorkbenchController de l’application soit en mesure de fonctionner correctement. L’interface IFilterFactory définit la méthode getFilter() utilisée par la classe FilterWorkbenchController : function getFilter():BitmapFilter;
{ // ------- Private vars ------private var _filter:ConvolutionFilter; BitmapFilter, soit une occurrence de n’importe quelle classe de filtre ActionScript.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Comme indiqué précédemment, l’application Filter Workbench utilise une occurrence de la classe FilterWorkbenchController (appelée à partir de maintenant l’« occurrence de contrôleur »), chargée d’appliquer les filtres à l’objet visuel sélectionné. Avant que l’occurrence de contrôleur ne puisse appliquer un filtre, elle doit identifier l’image ou le contenu visuel concerné. Lorsque l’utilisateur sélectionne une image, l’application appelle la méthode setFilterTarget() de la classe FilterWorkbenchController et transmet l’une des constantes définies dans la classe ImageType : public function setFilterTarget(targetType:ImageType):void { ... (Event.CHANGE) lorsque le filtre est modifié. Lorsque l’utilisateur modifie les propriétés d’un filtre dans le panneau des filtres, l’occurrence de contrôleur est avertie de la modification par l’événement change de Filter Factory, qui appelle la méthode filterChange() de l’occurrence de contrôleur. Cette méthode appelle alors la méthode applyTemporaryFilter() :
Remarque : Pixel Bender est pris en charge depuis Flash Player 10 et Adobe AIR 1.5. Les fusions, filtres et remplissages Pixel Bender ne sont pas pris en charge en cas de rendu par le processeur graphique.
Adobe Pixel Bender Technology Center Pixel Bender Developer’s Guide (disponible en anglais uniquement) Adobe Pixel Bender est un langage de programmation qui permet de créer ou de manipuler un contenu d’image. Par le biais de Pixel Bender, vous créez un noyau, également appelé un shader. Le shader définit une fonction unique exécutée séparément sur chacun des pixels d’une image. Le résultat de chaque appel à la fonction est la couleur de sortie aux coordonnées de ce pixel dans l’image. Vous pouvez spécifier des valeurs de paramètre et images d’entrée pour personnaliser l’opération. Si un shader est exécuté une seule fois, les valeurs de paramètres et d’entrée sont des constantes. Les seuls éléments qui varient sont les coordonnées du pixel dont la couleur est le résultat de l’appel de la fonction. Dans la mesure du possible, la fonction shader est appelée pour plusieurs coordonnées de pixel de sortie en parallèle. Les performances du shader sont ainsi optimisées et le traitement s’avère souvent particulièrement efficace. ActionScript permet de créer facilement trois types d’effets par le biais d’un shader :
• mode de fondu Pixel Bender est pris en charge depuis Flash Player version 10 et Adobe AIR version 1.5. Les fusions, filtres et remplissages Pixel Bender ne sont pas pris en charge en cas de rendu par processeur graphique. Sur un périphérique mobile, les shaders Pixel Bender sont exécutés en cas de rendu par unité centrale. Les performances ne sont toutefois pas à la hauteur de celles d’un poste de travail. De nombreux programmes de shader ne s’exécutent qu’à quelques images par seconde. Concepts importants et terminologie La liste de référence suivante contient des termes importants relatifs à la création et à l’utilisation de shaders de Pixel Bender : Noyau Pour Pixel Bender, un noyau est équivalent à un shader. Par le biais de Pixel Bender, votre code définit un
Pseudo-code binaire Pixel Bender Lorsqu’un noyau Pixel Bender est compilé, il est transformé en pseudo-code binaire
Langage Pixel Bender Langage de programmation utilisé pour créer un noyau Pixel Bender. Pixel Bender Toolkit Application utilisée pour créer un fichier de pseudo-code binaire Pixel Bender à partir du code source Pixel Bender. Elle vous permet d’écrire, de tester et de compiler un code source Pixel Bender. Shader Dans le cadre de ce document, un shader est un jeu de fonctionnalités écrites dans le langage Pixel Bender. Le
Bender et compilé en pseudo-code binaire Pixel Bender. Il peut être intégré à un fichier SWF lors de la compilation ou chargé en tant que fichier externe lors de l’exécution. Dans les deux cas, pour y accéder dans ActionScript, il est nécessaire de créer un objet Shader et de le lier au pseudo-code binaire du shader. Entrée du shader Entrée complexe, généralement composée de données d’image bitmap, fournie à un shader qui l’utilise dans ses calculs. Pour chaque variable d’entrée définie dans un shader, une valeur unique (une image unique ou un jeu de données binaires) est utilisée pour l’exécution de bout en bout du shader. Paramètre de shader Valeur unique (ou jeu de valeurs limité) fournie à un shader, qui l’utilise dans ses calculs. Chaque
Utilisation des exemples de code Il peut s’avérer utile de tester les exemples de code fournis. Cette opération nécessite d’exécuter le code et d’afficher les résultats dans le fichier SWF créé. Tous les exemples créent un contenu par le biais de l’API de dessin qui utilise l’effet de shader ou est modifiée par ce dernier. La plupart des exemples de code se composent de deux parties. La première partie correspond au code source Pixel Bender associé au shader utilisé dans l’exemple. Vous devez commencer par utiliser Pixel Bender Toolkit pour compiler le code source dans un fichier de pseudo-code binaire Pixel Bender. Procédez comme suit pour créer le fichier de pseudo-code binaire Pixel Bender : 1 Ouvrez Adobe Pixel Bender Toolkit. Le cas échéant, dans le menu Build (Développement), choisissez « Turn on
3 Dans le menu File (Fichier), choisissez « Export kernel filter for Flash Player » (Exporter le filtre de noyau associé
4 Enregistrez le fichier de pseudo-code binaire Pixel Bender dans le même répertoire que le document Flash. Le nom
La partie ActionScript de chaque exemple est écrite en tant que fichier de classe. Pour tester l’exemple dans Flash Professional : 1 Créez un document Flash vide et enregistrez-le sur votre ordinateur. 2 Créez un nouveau fichier ActionScript et enregistrez-le dans le même répertoire que le document Flash. Le nom du
3 Copiez le code dans le fichier ActionScript et enregistrez le fichier. 4 Dans le document Flash, cliquez sur une partie vide de la scène ou de l’espace de travail pour activer l’Inspecteur
5 Dans l’Inspecteur des propriétés, dans le champ Classe du document, saisissez le nom de la classe ActionScript que
6 Exécutez le programme en sélectionnant Contrôle > Tester l’animation.
Ces techniques de test des exemples de code font l’objet d’une description détaillée dans « Utilisation des exemples de code ActionScript » à la page 1145.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures La première étape dans l’utilisation d’un shader de Pixel Bender dans ActionScript consiste à pouvoir accéder au shader en code ActionScript. Comme un shader est créé à l’aide d’Adobe Pixel Bender Toolkit et rédigé dans le langage Pixel Bender, on ne peut pas y accéder directement dans ActionScript. Il faut plutôt créer une occurrence de la classe Shader qui représente le shader de Pixel Bender à ActionScript. L’objet Shader vous permet de trouver les informations concernant le shader : par exemple, s’il prévoit de recevoir des paramètres ou des valeurs pour l’image d’entrée. Vous passez l’objet Shader aux autres objets pour utiliser effectivement le shader. Par exemple, pour utiliser le shader comme filtre, vous affectez l’objet Shader à la propriété shader d’un objet ShaderFilter. Ou bien, afin d’utiliser le shader pour remplir l’écran dans un dessin, vous passez l’objet Shader comme argument à la méthode Graphics.beginShaderFill(). Votre code ActionScript peut accéder à un shader créé par Adobe Pixel Bender Toolkit (un fichier .pbj) de deux façons distinctes :
URLLoader. Cette technique est comparable au chargement d’un élément externe, comme un fichier texte, par exemple. L’exemple suivant montre le chargement à l’exécution d’un fichier de pseudo-code binaire de shader et sa liaison à une occurrence de Shader :
Shader pour accéder aux métadonnées du shader, spécifier les images d’entrée et spécifier les valeurs du paramétrage.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures Tandis qu’il crée un noyau de shader de Pixel Bender, le programmeur peut spécifier des métadonnées sur le shader dans le code source Pixel Bender. Vous pouvez inspecter le shader et extraire ses métadonnées pendant que vous l’utilisez dans ActionScript. Lorsque vous créez une occurrence de Shader et que vous la liez à un shader de Pixel Bender, un objet ShaderData, qui contient des données sur le shader, est créé et enregistré dans la propriété data de l’objet Shader. La classe ShaderData ne définit aucune de ses propres propriétés. Toutefois, lors de l’exécution, une propriété est ajoutée dynamiquement à l’objet ShaderData pour chaque valeur de métadonnées définie dans le code source du shader. Le nom attribué à chaque propriété est pareil à celui spécifié dans les métadonnées. Par exemple, supposez que le code source d’un shader de Pixel Bender contienne la définition des métadonnées suivante : namespace : "Adobe::Example"; vendor : "Bob Jones"; version : 1; description : "Creates a version of the specified image with the specified brightness.";
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures De nombreux shaders de Pixel Bender sont définis pour faire appel à une ou plusieurs images utilisées au cours de son traitement. Par exemple, il est courant pour un shader d’accepter une image source et de la produire dotée d’un effet particulier. Suivant l’utilisation du shader, soit la valeur d’entrée est spécifiée automatiquement, soit il faut en fournir une. De la même façon, de nombreux shaders spécifient des paramètres utilisés dans l’individualisation de ce qu’ils produisent. Il faut également définir explicitement une valeur pour chaque paramètre avant d’utiliser le shader. Vous utilisez la propriété data de l’objet Shader pour définir les entrées et les paramètres et pour établir si un shader en particulier prévoit des entrées et des paramètres. La propriété data est une occurrence de ShaderData.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures La première étape dans la spécification de valeurs d’entrée et de paramètres d’un shader consiste à savoir si celui que vous utilisez prévoit de recevoir des images d’entrée ou des paramètres. Chaque occurrence de Shader possède une propriété data qui contient un objet ShaderData. Si le shader spécifie des entrées ou des paramètres, on y accède en tant que propriétés de cet objet ShaderData. Les noms des propriétés correspondent aux noms spécifiés dans le code source du shader pour les entrées et les paramètres. Par exemple, si un shader spécifie une entrée appelée src, l’objet ShaderData possède une propriété appelée src qui représente cette entrée. Chaque propriété qui représente une entrée est une occurrence de ShaderInput et chaque propriété qui représente un paramètre est une occurrence de ShaderParameter. Idéalement, le programmeur du shader fournit une documentation pour le shader afin de décrire quels sont les paramètres et les valeurs de l’image d’entrée qu’il prévoit, ce qu’ils représentent, les valeurs appropriées, et ainsi de suite. Toutefois, si le shader n’est pas documenté et que vous ne disposez pas du code source, vous pouvez inspecter les données du shader pour identifier ces entrées et paramètres. Les propriétés qui représentent ces entrées et paramètres sont ajoutées dynamiquement à l’objet ShaderData. Par conséquent, vous pouvez utiliser une boucle for..in pour inspecter l’objet ShaderData afin de savoir si le shader qui lui est associé spécifie de tels entrées ou paramètres. Comme le décrit la section « Accès aux métadonnées du shader » à la page 314, on accède également, en tant que propriété dynamique ajoutée à la propriété Shader.data, à toute valeur de métadonnées définie pour un shader. Lorsque vous utilisez cette technique afin d’identifier entrées et paramètres, vérifiez le type de données des propriétés dynamiques. Si une propriété est une occurrence de ShaderInput, elle représente une entrée. S’il s’agit d’une occurrence de ShaderParameter, elle représente un paramètre. Sinon, il s’agit d’une valeur de métadonnées. L’exemple ci-dessous montre comment utiliser une boucle for..in pour examiner les propriétés dynamiques de la propriété data d’un shader. Chaque entrée (objet ShaderInput) est ajoutée à une occurrence de Vector appelée inputs. Chaque paramètre (objet ShaderParameter) est ajouté à une occurrence de Vector appelée parameters. Enfin, toute propriété de métadonnées est ajoutée à une occurrence de Vector appelée metadata. Remarquez que cet exemple suppose qu’une occurrence de Shader appelée myShader existe déjà :
Par exemple, supposons qu’un shader ait besoin d’une entrée et qu’il serve de filtre. Lorsque le filtre est appliqué à un objet d’affichage ou BitmapData, cet objet est défini automatiquement comme entrée. Dans ce cas, on ne spécifie pas explicitement une valeur d’entrée. Toutefois, dans certains cas, et plus particulièrement si un shader spécifie plusieurs entrées, il faut définir explicitement une valeur pour l’entrée. Toute entrée définie dans un shader est représentée dans ActionScript par un objet ShaderInput. L’objet ShaderInput est une propriété de l’occurrence de ShaderData dans la propriété data de l’objet Shader (voir « Identification des entrées et des paramètres d’un shader » à la page 315). Par exemple, supposons qu’un shader définisse une entrée appelée src et qu’il soit lié à un objet Shader appelé myShader. Vous accédez alors à l’objet ShaderInput qui correspond à l’entrée src à l’aide de l’identifiant suivant : myShader.data.src
Chaque objet ShaderInput possède également une propriété index qui est utile afin de déterminer si une valeur explicite doit être fournie pour l’entrée. Si un shader prévoit de recevoir davantage d’entrées que le nombre fixé automatiquement, vous pouvez alors définir des valeurs pour ces entrées. Pour plus de détails sur les différentes façons d’utiliser un shader et pour savoir si oui ou non les valeurs d’entrée sont fixées automatiquement, voir « Utilisation d’un shader » à la page 320.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures Certains shaders définissent des valeurs de paramètres qu’ils utilisent dans la création de leur résultat. Par exemple, un shader qui modifie la luminosité d’une image pourrait spécifier un paramètre de luminosité qui détermine dans quelle mesure l’opération affecte cette luminosité. Un paramètre unique défini dans un shader peut prévoir une ou plusieurs valeurs suivant la façon dont il a été spécifié dans le shader. Tout paramètre défini dans un shader est représenté dans ActionScript par un objet ShaderParameter. L’objet ShaderParameter est une propriété de l’occurrence de ShaderData dans la propriété des données de l’objet Shader. Une description se trouve dans la section « Identification des entrées et des paramètres d’un shader » à la page 315. Par exemple, supposons qu’un shader qui définit un paramètre appelé luminosité soit représenté par un objet Shader appelé myShader. Vous accédez alors à l’objet ShaderParameter correspondant au paramètre luminosité à l’aide de l’identifiant suivant : myShader.data.brightness
ShaderParameter.value. Le code suivant montre comment définir une seule valeur pour la propriété value. myShader.data.brightness.value = [75];
être modifiée en changeant la valeur de l’élément du tableau. Il n’est pas nécessaire de créer un autre tableau et de l’affecter à la propriété value. L’exemple ci-dessous indique comment définir une valeur de paramètre dans un shader avec ActionScript. Dans cet exemple, le shader définit un paramètre appelé color. Ce paramètre color est déclaré en tant que variable float4 dans le code source Pixel Bender, ce qui signifie qu’il s’agit d’un tableau à quatre nombres en virgule flottante. Dans l’exemple, la valeur du paramètre color change constamment. A chaque changement, le shader est utilisé pour dessiner un rectangle coloré à l’écran. Il en résulte un changement de couleur animé. Remarque : le code de cet exemple a été rédigé par Ryan Taylor. Merci Ryan de bien vouloir nous en faire profiter. Vous pouvez accéder aux exemples de Ryan et lire ses commentaires à l’adresse www.boostworthy.com/. Le code ActionScript repose sur l’utilisation de trois méthodes :
Dernière mise à jour le 27/4/2013
ShaderParameter.value dans le Guide de référence ActionScript 3.0 pour Flash Professional.
ShaderParameter en tant que propriétés dynamiques. Pour passer en revue ces propriétés, utilisez une boucle for..in pour boucler dans les propriétés dynamiques de l’objet ShaderParameter afin d’identifier ses métadonnées. L’exemple ci-dessous montre comment utiliser une boucle for..in afin d’identifier les métadonnées d’un objet ShaderParameter. Chaque valeur de métadonnées est ajoutée à une occurrence de Vector appelée metadata. Remarquez que cet exemple suppose qu’une occurrence de Shader appelée myShader existe déjà et qu’elle possède un paramètre appelé brightness. var brightness:ShaderParameter = myShader.data.brightness; var metadata:Vector.<String> = new Vector.<String>(); for (var prop:String in brightness) { if (brightness[prop] is String) { metadata[metadata.length] = brightness[prop]; } • Traitement d’un shader autonome : le traitement du shader se fait sans définir l’usage de la sortie. Sur demande, le shader peut tourner en arrière-plan de telle sorte que le résultat devient disponible à la fin du traitement. Cette technique peut être utilisée pour générer des données bitmap et traiter des données non visuelles.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures Si vous utilisez un shader pour créer un remplissage de dessin, vous faites appel aux méthodes de l’API de dessin pour créer une forme vectorielle. La sortie du shader permet de remplir la forme, à l’instar de toute image bitmap utilisée en tant que remplissage de bitmap par l’API de dessin. Pour créer un remplissage de dessin, appelez la méthode beginShaderFill() de l’objet Graphics à l’emplacement du code où vous souhaitez commencer à dessiner la forme. Transmettez l’objet Shader en tant que premier argument à la méthode beginShaderFill(), comme illustré dans le code suivant :
Remarque : le code de cet exemple a été rédigé par Petri Leskinen. Merci Petri de bien vouloir nous en faire profiter. Vous pouvez consulter d’autres exemples et didacticiels rédigés par Petri à l’adresse http://pixelero.wordpress.com/. Le code ActionScript réside dans trois méthodes :
Sprite appelée canvas. Ultérieurement, dans la méthode updateShaderFill(), le code dessine une fois par image le résultat du shader dans canvas. Enfin, le code charge le fichier de pseudo-code binaire du shader.
dessiner le résultat du shader dans un triangle. Vous trouverez ci-dessous le code ActionScript associé à cet exemple : Utilisez cette classe en tant que classe d’application principale d’un projet ActionScript uniquement dans Flash Builder, ou en tant que classe de document d’un fichier FLA dans Flash Professional :
Utilisation d’un shader comme mode de fondu Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures Utiliser un shader comme mode de fondu s’apparente à l’utilisation des autres modes de fondu. Le shader définit le résultat de deux objets d’affichage fondus visuellement. Pour utiliser un shader en tant que mode de fondu, affectez à votre objet Shader la propriété blendShader de l’objet d’affichage en premier plan. Affecter une valeur autre que null à la propriété blendShader définit automatiquement la propriété blendMode de l’objet d’affichage sur BlendMode.SHADER. Le code suivant illustre l’utilisation d’un shader en tant que mode de fondu. Notez que cet exemple part du principe qu’un objet d’affichage appelé foreground figure dans le même parent que l’autre contenu d’affichage dans la liste d’affichage, sachant que foreground chevauche l’autre contenu : foreground.blendShader = myShader;
L’exemple suivant illustre l’utilisation d’un shader en tant que mode de fondu. Cet exemple utilise un mode de fondu Eclaircir basé sur la luminosité. Ce fondu a pour résultat d’afficher le pixel le plus clair de l’un ou l’autre des objets fondus. Remarque : le code de cet exemple a été rédigé par Mario Klingemann. Merci Mario de bien vouloir nous en faire profiter. Pour consulter d’autres exemples de code rédigés par Mario, ainsi que ses commentaires, voir www.quasimondo.com/. Le code ActionScript important figure dans les deux méthodes suivantes :
Toutefois, si le mode de fondu est affiché, la section la plus lumineuse de l’ellipse verte est visible, car elle est plus claire que la section de foregroundShape qui la recouvre :
Il est ainsi impossible de se baser sur la position d’un pixel pour affecter la combinaison des images fusionnées.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures Utiliser un shader comme filtre s’apparente à l’utilisation de tout autre filtre dans ActionScript. Lorsque vous utilisez un shader en tant que filtre, l’image filtrée (un objet d’affichage ou un objet BitmapData) est transmise au shader. Le shader utilise l’image d’entrée pour créer le résultat du filtre, qui correspond généralement à une version modifiée de l’image d’origine. Si l’objet filtré est un objet d’affichage, le résultat du filtre remplace l’objet d’affichage filtré à l’écran. Si l’objet filtré est un objet BitmapData, le résultat du shader devient le contenu de l’objet BitmapData dont la méthode applyFilter() est appelée. Pour utiliser un shader en tant que filtre, vous commencez par créer l’objet Shader, comme indiqué à la section « Chargement ou intégration d’un shader » à la page 312. Vous créez ensuite un objet ShaderFilter lié à l’objet Shader. L’objet ShaderFilter est le filtre appliqué à l’objet filtré. Vous l’appliquez à un objet à l’instar de n’importe quel filtre. Vous le transmettez à la propriété filters d’un objet d’affichage ou vous appelez la méthode applyFilter() sur un objet BitmapData. Par exemple, le code suivant crée un objet ShaderFilter et applique le filtre à un objet d’affichage appelé homeButton. var myFilter:ShaderFilter = new ShaderFilter(myShader); homeButton.filters = [myFilter];
Dans certains cas, un filtre modifie les dimensions de l’image d’origine. Un effet d’ombre portée standard ajoute par exemple des pixels contenant l’ombre associée à l’image. Lorsque vous utilisez un shader qui modifie les dimensions de l’image, définissez les propriétés leftExtension, rightExtension, topExtension et bottomExtension pour indiquer l’écart approprié. L’exemple suivant illustre l’utilisation d’un shader en tant que filtre. Dans cet exemple, le filtre inverse les valeurs des canaux rouge, vert et bleu d’une image. Il a pour résultat un « négatif » de l’image. Remarque : cet exemple utilise comme shader le noyau invertRGB.pbk Pixel Bender intégré à Pixel Bender Toolkit. Vous pouvez charger le code source du noyau à partir du répertoire d’installation de Pixel Bender Toolkit. Compilez le code source, puis enregistrez le fichier de pseudo-code binaire dans le même répertoire que le code source. Le code ActionScript important figure dans les deux méthodes suivantes :
Si le filtre est appliqué, les couleurs sont inversées, auquel cas l’apparence du rectangle est la suivante :
Toolkit. Compilez le code source et enregistrez le fichier de pseudo-code binaire sous le nom « invertRGB.pbj » dans le même répertoire que votre code source ActionScript. Vous trouverez ci-dessous le code ActionScript associé à cet exemple : Utilisez cette classe en tant que classe d’application principale d’un projet ActionScript uniquement dans Flash Builder, ou en tant que classe de document du fichier FLA dans Flash Professional :
Lorsque vous utilisez un shader en mode autonome, son traitement s’exécute indépendamment de l’usage prévu du résultat. Vous spécifiez le shader à exécuter, définissez les valeurs d’entrée et de paramètres, puis stipulez un objet dans lequel seront placées les données résultantes. Vous pouvez utiliser un shader en mode autonome pour deux raisons :
à tourner et que votre code est averti une fois le traitement du shader terminé. Vous pouvez utiliser un shader sans pour autant bloquer l’interface utilisateur de l’application ou tout autre traitement, même si la durée de son exécution est élevée. Un objet ShaderJob permet d’exécuter un shader en mode autonome. Vous commencez par créer un objet ShaderJob et vous le liez à l’objet Shader qui représente le shader à exécuter : var job:ShaderJob = new ShaderJob(myShader);
écouteur est appelé lorsque le shader termine sa tâche : function completeHandler(event:ShaderEvent):void { // do something with the shader result } job.addEventListener(ShaderEvent.COMPLETE, completeHandler); Remarque : vous pouvez définir les propriétés shader, target,width et height de l’objet ShaderJob en une seule étape. Pour ce faire, transmettez les arguments au constructeur ShaderJob(), comme suit :var job:ShaderJob = new ShaderJob(myShader, myTarget, myWidth, myHeight);. Lorsque vous êtes prêt à exécuter le shader, vous appelez la méthode start() de l’objet ShaderJob : job.start();
Une fois l’opération du shader terminée, l’objet ShaderJob appelle ses écouteurs d’événement complete et les avertit. A ce stade (en d’autres termes, dans le corps de votre écouteur d’événement complete), l’objet target contient le résultat de l’opération du shader.
événement qui est transmis à la méthode d’écouteur. L’objet événement est une occurrence de ShaderEvent. L’objet ShaderEvent possède trois propriétés susceptibles d’être utilisées pour accéder au résultat, selon le type de données de l’objet défini en tant que propriété target : ShaderEvent.bitmapData, ShaderEvent.byteArray et ShaderEvent.vector. Vous pouvez également transmettre un argument true à la méthode start(). Dans ce cas, l’opération du shader s’exécute en mode synchrone. Tout le code (y compris l’interaction avec l’interface utilisateur et tout autre événement) est interrompu pendant l’exécution du shader. Une fois le shader terminé, l’objet target en contient le résultat et le programme passe à la ligne de code suivante. job.start(true);
Principes de base des clips Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les clips sont un élément capital pour les créateurs de contenu animé dans l’environnement de création Flash et pour contrôler ce contenu avec ActionScript. Lorsque vous créez un symbole de clip dans Flash, le programme ajoute ce symbole à la bibliothèque du document Flash. Par défaut, ce symbole devient une occurrence de la classe MovieClip et, de ce fait, possède les propriétés et méthodes de cette classe. Lorsqu’une occurrence d’un symbole de clip est placée sur la scène, la progression du scénario de ce clip s’effectue automatiquement (si le clip comporte plusieurs images), sauf si cette lecture est modifiée en ActionScript. Le scénario est l’élément distinctif de la classe MovieClip. Il permet de créer des animations par interpolation de mouvement ou de forme via l’interface de Flash. Par contre, un objet d’affichage issu de la classe Sprite peut uniquement être animé par programmation, en modifiant ses valeurs. Dans les versions précédentes d’ActionScript, la classe MovieClip constituait la classe de base de toutes les occurrences de la scène. En ActionScript 3.0, un clip est désormais un objet d’affichage parmi d’autres, tous susceptibles de s’afficher à l’écran. S’il n’est pas nécessaire de définir un scénario pour la fonction d’un objet d’affichage, l’utilisation de la classe Shape au lieu de la classe MovieClip peut accroître les performances d’affichage. Pour plus d’informations sur le choix des objets d’affichage en fonction de la tâche prévue, voir « Sélection d’une sous-classe de DisplayObject » à la page 179. Concepts importants et terminologie La liste de référence suivante contient des termes importants relatifs aux clips : Fichier SWF AVM1 Fichier SWF créé en ActionScript 1.0 ou ActionScript 2.0, et généralement destiné aux versions 8
Fichier SWF AVM2 Fichier SWF créé en ActionScript 3.0 pour Adobe Flash Player 9 ou ultérieur ou Adobe AIR. Fichier SWF externe Fichier SWF créé séparément du fichier SWF du projet, et destiné à être chargé et lu dans celui-ci. Image Elément de base du scénario. Comme les images de films, chaque image est une « photographie » et c’est la
Scénario Métaphore représentant la série d’images qui composent la séquence d’animation d’un clip. Le scénario d’un
Tête de lecture Marqueur identifiant la position (l’image) dans le scénario qui est affichée à un moment donné.
Utilisation des clips
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lorsque vous publiez un fichier SWF, Flash convertit toutes les occurrences de symboles de clips sur la scène en objets MovieClip. Pour qu’un symbole de clip soit disponible en ActionScript, donnez-lui un nom d’occurrence dans le champ Nom de l’occurrence de l’Inspecteur des Propriétés. Lors de la création du fichier SWF, Flash génère le code qui crée l’occurrence de MovieClip sur la scène et déclare une variable avec ce nom d’occurrence. Si les clips que vous avez nommés sont imbriqués dans d’autres clips nommés, ces clips enfant sont traités comme des propriétés du clip parent : vous pouvez accéder à tous les clips de cette hiérarchie en utilisant la syntaxe à point. Par exemple, si une occurrence de clip appelée childClip est imbriquée dans une autre appelée parentClip, vous pouvez lancer sa lecture en appelant le code suivant : parentClip.childClip.play();
été créées. Avant d’accéder à l’enfant, le parent doit soit créer l’occurrence enfant par du code, soit retarder l’accès à une fonction de rappel qui écoute l’enfant en vue de la distribution de son événement Event.ADDED_TO_STAGE. Si de nombreuses méthodes et propriétés de la classe MovieClip d’ActionScript 2.0 restent les mêmes, d’autres ont changé. Toutes les propriétés qui étaient préfixées d’un trait de soulignement ont été renommées. Par exemple, les propriétés _width et _height sont désormais accessibles sous le nom width et height, _xscale et _yscale sous le nomscaleX et scaleY. Pour obtenir la liste complète des propriétés et méthodes de la classe MovieClip, voir le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Flash utilise la métaphore du scénario pour traduire une animation ou un changement d’état. Tout élément visuel qui a recours à un scénario est soit un objet MovieClip, soit une extension de la classe MovieClip. Bien qu’il soit possible en ActionScript de commander l’arrêt ou la lecture d’un clip et le passage à un autre point du scénario, il n’est pas possible de créer dynamiquement un scénario ni d’ajouter du contenu dans une image spécifique. Seul l’outil de programmation Flash le permet. Pendant la lecture, le clip progresse le long du scénario à une vitesse fixée par la cadence d’image du fichier SWF. Vous pouvez également ignorer ce paramètre et le remplacer par la propriété Stage.frameRate dans ActionScript.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les méthodes play() et stop() permettent d’effectuer des manipulations simples sur un clip tout au long du scénario. Par exemple, supposons qu’un symbole de clip sur la scène contienne une animation représentant une bicyclette qui traverse l’écran, et dont le nom d’occurrence est bicycle. Si le code suivant est associé à une image-clé du scénario principal, bicycle.stop();
également avancer et reculer manuellement la tête de lecture à l’aide des méthodes nextFrame() et prevFrame(). L’appel de l’une de ces deux méthodes arrête la lecture et fait avancer le clip ou le rembobine d’une image. L’utilisation de la méthode play() revient à appeler nextFrame() chaque fois qu’un événement enterFrame est déclenché pour cet objet clip. Vous pouvez donc envisager de lire le clip bicycle en arrière en ajoutant un écouteur pour l’événement enterFrame et en indiquant à bicycle, dans la fonction écouteur, de reculer d’une image, comme suit : // This function is called when the enterFrame event is triggered, meaning // it's called once per frame. function everyFrame(event:Event):void { if (bicycle.currentFrame == 1) Dernière mise à jour le 27/4/2013
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le déplacement d’un clip à une nouvelle image est une opération simple. Il suffit d’appeler gotoAndPlay() ou gotoAndStop() en spécifiant le numéro de l’image cible comme paramètre. Vous pouvez également transmettre une chaîne correspondant au nom de l’étiquette d’image. Il est possible d’attribuer une étiquette à toute image du scénario. Pour ce faire, sélectionnez une image du scénario, puis tapez un nom dans le champ Etiquette d’image de l’Inspecteur des Propriétés. L’utilisation des étiquettes d’image plutôt que des numéros présente des avantages évidents pour créer un clip complexe. Si le nombre d’images, de calques et d’interpolations d’une animation est élevé, envisagez d’étiqueter les images importantes de manière évocatrice, en faisant référence aux changements de comportement dans le clip (par exemple « départ », « marche » ou « course »). Cette technique permet d’améliorer la lisibilité du code et offre plus de souplesse, puisque les appels ActionScript destinés à une image étiquetée pointent sur une référence uniquement (l’étiquette) plutôt que sur une image numérotée. Si vous décidez par la suite de déplacer un segment de l’animation vers une autre image, il ne sera pas nécessaire de modifier le code ActionScript si vous conservez les mêmes étiquettes pour toutes les images au nouvel emplacement. Pour représenter des étiquettes en code, ActionScript 3.0 comporte la classe FrameLabel. Chaque occurrence de cette classe représente une étiquette d’image unique, et possède une propriété name qui représente le nom de l’étiquette tel qu’il a été indiqué dans l’Inspecteur des Propriétés, ainsi qu’une propriété frame qui représente le numéro de l’image pour laquelle l’étiquette est placée dans le scénario. Pour permettre d’accéder aux occurrences de FrameLabel associées à une occurrence de clip, la classe MovieClip comporte deux propriétés qui renvoient directement des objets FrameLabel. La propriété currentLabels renvoie un tableau composé de tous les objets FrameLabel présents sur l’ensemble du scénario d’un clip. La propriété currentLabel renvoie une chaîne contenant le nom de l’étiquette d’image trouvée récemment sur le scénario. Supposons que vous ayez créé un clip nommé Robot et que vous ayez étiqueté les différents états de l’animation. Vous pouvez définir une condition pour vérifier la propriété currentLabel afin d’accéder à l’état actuel de Robot, comme dans le code suivant : if (robot.currentLabel == "walking") { // do something } Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Dans l’environnement de création Flash, vous pouvez utiliser les séquences pour démarquer une série de scénarios qu’un fichier SWF doit suivre. Grâce au second paramètre de la méthode gotoAndPlay() ou gotoAndStop(), vous pouvez spécifier la séquence sur laquelle la tête de lecture doit se placer. Tous les fichiers FLA commencent par une séquence, à laquelle vous pouvez ajouter le nombre de séquences de votre choix. L’utilisation des séquences n’est pas toujours conseillée, car elle présente un certain nombre d’inconvénients. La maintenance d’un document Flash qui contient de nombreuses séquences peut être difficile, en particulier dans les environnements où plusieurs auteurs interviennent. Un nombre élevé de séquences peut également s’avérer inefficace de point de vue de la bande passante, car le processus de publication implique la fusion de toutes les séquences en un seul scénario. L’ensemble des séquences est alors téléchargé en mode progressif, même si elles ne sont jamais lues. C’est pourquoi l’utilisation de plusieurs séquences est largement déconseillée, à moins qu’elle soit nécessaire à l’organisation de plusieurs animations basées sur des scénarios. La propriété scenes de la classe MovieClip renvoie un tableau des objets Scene représentant toutes les séquences du fichier SWF. La propriété currentScene renvoie un objet Scene représentant la séquence qui est en cours de lecture. La classe Scene a des propriétés qui contiennent des informations sur la séquence. La propriété labels renvoie un tableau des objets FrameLabel utilisés au sein de la séquence. La propriété name renvoie le nom de la séquence sous forme de chaîne. La propriété numFrames renvoie un entier représentant le nombre total d’images dans la séquence.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’ajout de contenu s’effectue dans Flash en faisant glisser des éléments de la bibliothèque sur la scène. Mais il ne s’agit pas là de la seule méthode. Pour des projets plus complexes, les développeurs expérimentés préfèrent souvent créer les clips par programmation. Cette approche présente plusieurs avantages : réutilisation facile du code, vitesse de compilation accrue et disponibilité de modifications plus sophistiquées réservées à ActionScript. La nouvelle API de liste d’affichage d’ActionScript 3.0 simplifie le processus de création dynamique d’objets MovieClip. La possibilité d’instancier directement une occurrence de MovieClip, séparément de son ajout à la liste d’affichage, offre beaucoup de souplesse et de simplicité sans sacrifier tout contrôle. En ActionScript 3.0, lorsqu’une occurrence de clip (ou de tout autre objet d’affichage) est créée par code, elle est invisible tant qu’elle n’a pas été ajoutée à la liste d’affichage à l’aide de la méthode addChild() ou addChildAt() d’un conteneur d’objets d’affichage Vous pouvez ainsi créer un clip et définir ses propriétés, et même appeler ses méthodes, avant qu’il apparaisse à l’écran. Pour plus d’informations sur l’utilisation de la liste d’affichage, voir « Utilisation de conteneurs d’objets d’affichage » à la page 165.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Par défaut, il est impossible de créer dynamiquement des occurrences de symboles de clips dans la bibliothèque d’un document Flash (c’est-à-dire de les créer entièrement en ActionScript). En effet, l’exportation de chaque symbole pour une utilisation en ActionScript accroît la taille du fichier SWF. Or, les symboles ne sont pas tous destinés à une utilisation sur la scène. C’est pourquoi, pour qu’un symbole soit disponible en ActionScript, vous devez indiquer spécifiquement que ce symbole doit être exporté pour ActionScript. Pour exporter un symbole pour ActionScript : 1 Sélectionnez le symbole dans le panneau Bibliothèque et ouvrez sa boîte de dialogue Propriétés. 2 Si nécessaire, activez les paramètres avancés. 3 Dans la boîte de dialogue Liaison, activez l’option Exporter pour ActionScript.
Par défaut, le champ Classe contient le nom du symbole sans espaces (par exemple, un symbole nommé « Maison Rouge » devient « MaisonRouge »). Pour spécifier que le symbole doit utiliser une classe personnalisée pour son comportement, saisissez le nom complet de cette classe, package compris. Si vous voulez avoir la possibilité de créer des occurrences du symbole en ActionScript, sans avoir pour autant besoin de comportements supplémentaires, vous pouvez laisser ce nom de classe tel quel. Par défaut, le champ Classe de base a la valeur flash.display.MovieClip. Si vous voulez que votre symbole étende les fonctionnalités d’une autre classe personnalisée, vous pouvez remplacer cette valeur par le nom de votre classe, sous réserve que celle-ci étende la classe Sprite (ou MovieClip). 4 Cliquez sur OK pour enregistrer les changements.
Le chemin de classe ne contient pas de définition pour cette classe. Une définition sera générée automatiquement dans le fichier SWF lors de l’exportation. Vous pouvez ignorer cet avertissement si le symbole de bibliothèque ne nécessite pas de fonctionnalités en dehors de celles de la classe MovieClip. Si vous n’indiquez aucune classe pour votre symbole, Flash crée pour lui une classe du type de celle-ci : package { import flash.display.MovieClip; public class ExampleMovieClip extends MovieClip { public function ExampleMovieClip() { Circle. Le code suivant, lorsqu’il est placé dans un fichier Circle.as, étend la classe MovieClip et fournit au symbole les méthodes supplémentaires getArea() et getCircumference() : package { import flash.display.MovieClip; public class Circle extends MovieClip { public function Circle() { Il crée un cercle qui présente toutes les propriétés d’un clip et possède les méthodes personnalisées définies dans votre classe Circle. Il s’agit d’un exemple tout à fait élémentaire ; un symbole de bibliothèque peut spécifier un nombre illimité de propriétés et de méthodes dans sa classe. L’instanciation en ActionScript est un processus puissant, car il permet de créer dynamiquement de nombreuses occurrences qu’il serait particulièrement laborieux de créer manuellement. Elle vous apporte en outre une grande souplesse, puisque vous pouvez personnaliser les propriétés de chaque occurrence dès sa création. Pour saisir l’importance de ces avantages, vous pouvez utiliser une boucle pour créer dynamiquement plusieurs occurrences de Circle. Après avoir ajouté le symbole Circle et la classe correspondante, décrits précédemment, dans la bibliothèque de votre document Flash, placez le code suivant dans une image-clé à l’image 1 :
2 Créer un objet Loader. 3 Appeler la méthode load() de l’objet Loader en lui passant en paramètre l’occurrence de l’objet URLRequest. 4 Appeler la méthode addChild() pour un conteneur d’objet d’affichage (par exemple le scénario principal d’un
Le code final se présente ainsi : var request:URLRequest = new URLRequest("http://www.[yourdomain].com/externalSwf.swf"); var loader:Loader = new Loader() loader.load(request); addChild(loader);
Pour plus d’informations sur la sécurité et le domaine d’application, voir « Utilisation de domaines d’application » à la page 152 et « Chargement de contenu » à la page 1104. Une fois que le fichier SWF externe est chargé, il devient accessible via la propriété Loader.content. Si ce fichier est publié en ActionScript 3.0, il s’agira soit d’un clip, soit d’un sprite, selon la classe qu’il étend. Il existe quelques différences entre le chargement d’un fichier SWF dans Adobe AIR pour iOS et le chargement dans d’autres plates-formes. Pour plus d’informations, voir « Chargement de fichiers SWF dans AIR pour iOS » à la page 209.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Si un fichier SWF externe a été publié dans une version antérieure d’ActionScript, il faut tenir compte de restrictions importantes. Contrairement à un fichier SWF ActionScript 3.0 qui s’exécute dans AVM2 (ActionScript Virtual Machine 2), un fichier SWF publié en ActionScript 1.0 ou 2.0 s’exécute dans AVM1 (ActionScript Virtual Machine 1). Le chargement d’un fichier SWF ActionScript 1.0 ou 2.0 dans un fichier SWF ActionScript 3.0 présente d’importantes différences par rapport au chargement d’un fichier SWF ActionScript 3.0. Flash Player garantit une compatibilité totale avec les versions précédentes et les contenus publiés antérieurement. Tout contenu qui s’exécute dans les versions antérieures de Flash Player s’exécute dans les versions de Flash Player qui gèrent ActionScript 3.0. Tenez cependant compte des restrictions suivantes :
AVM1Movie. Une occurrence d’AVM1Movie n’est pas identique à une occurrence de MovieClip. C’est un objet d’affichage qui, contrairement à un clip, ne comporte pas de méthodes ni de propriétés liées au scénario. Le fichier SWF AVM2 parent ne peut pas accéder aux propriétés, méthodes ou objets de l’objet AVM1Movie chargé.
ActionScript 3.0. Cela signifie que les fichiers SWF créés dans Flash 8, Flex Builder 1.5 ou une version antérieure ne peuvent pas charger les fichiers SWF écrits en ActionScript 3.0. Il existe une seule exception à cette règle : un fichier SWF écrit en ActionScript 2.0 peut être remplacé par un fichier SWF écrit en ActionScript 3.0, sous réserve que le fichier écrit en ActionScript 2.0 n’ait effectué aucun chargement à quelque niveau que ce soit. Pour ce faire, le fichier SWF écrit en ActionScript 2.0 doit appeler loadMovieNum() et transmettre la valeur 0 au paramètre level.
Néanmoins, si vous créez un lecteur multimédia en ActionScript 3.0, il peut effectuer de simples chargements de votre contenu en ActionScript 2.0.
écrits en différentes versions d’ActionScript. Fonctionnalité prise en charge
être réutilisées sur plusieurs projets. Si Flash Player ou AIR exécute un fichier SWF, les symboles ayant été exportés dans ActionScript sont disponibles pour tous les fichiers SWF au sein du même sandbox de sécurité que le fichier SWF qui le charge. De cette manière, un seul document Flash peut générer un fichier SWF destiné uniquement à accueillir des éléments graphiques. Cette technique est très utile pour les grands projets dans lesquels les concepteurs graphiques chargés des éléments visuels peuvent travailler en parallèle avec les développeurs qui créent une « enveloppe » SWF qui chargera les fichiers SWF des éléments graphiques au moment de l’exécution. Cette méthode peut vous servir dans la maintenance d’un ensemble de versions de fichiers dans lesquelles les actifs graphiques ne sont pas dépendants du développement de la programmation. L’application RuntimeAssetsExplorer charge tout fichier SWF qui est une sous-classe de RuntimeAsset et permet de consulter les éléments disponibles de ce fichier SWF. Cet exemple illustre les points suivants :
• Création dynamique d’un symbole de bibliothèque exporté pour ActionScript • Contrôle de la lecture du MovieClip avec ActionScript Avant de commencer, notez que tous les fichiers SWF devant s’exécuter dans Flash Player doivent se trouver dans le même sandbox de sécurité. Pour plus d’informations, voir « Sandbox de sécurité » à la page 1087. Pour obtenir les fichiers d’application associés à cet exemple, téléchargez les exemples Flash Professional. Les fichiers de l’application RuntimeAssetsExplorer se trouvent dans le dossier Samples/Chapters/RuntimeAssetsExplorer. L’application se compose des fichiers suivants :
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour que l’explorateur interagisse convenablement avec une bibliothèque SWF, la structure des bibliothèques d’éléments doit être formalisée. Pour ce faire, nous allons créer une interface, que l’on pourrait comparer à une classe dans la mesure où elle représente un modèle de définition des méthodes qui définissent une structure attendue. Par contre, à l’inverse d’une classe, elle ne comporte pas les corps des méthodes. L’interface est un moyen de communication pour la bibliothèque d’éléments et l’explorateur. Chaque fichier SWF d’éléments chargé dans le navigateur implémentera cette interface. Pour plus d’informations sur l’utilité des interfaces, voir Interfaces dans Formation à ActionScript 3.0. L’interface RuntimeLibrary est très simple, puisque nous avons uniquement besoin d’une fonction qui fournisse à l’explorateur un tableau de chemins de classe pour les symboles à exporter disponibles dans la bibliothèque. Cette interface utilise pour ce faire une seule méthode : getAssets(). package com.example.programmingas3.runtimeassetexplorer { public interface RuntimeLibrary { function getAssets():Array; } Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La définition de l’interface RuntimeLibrary permet de créer plusieurs fichiers SWF de bibliothèque d’actifs, qui pourront être chargés dans un autre fichier SWF. L’élaboration d’une bibliothèque SWF d’actifs repose sur quatre tâches :
• Création de classes pour les différents éléments contenus dans la bibliothèque • Création des éléments graphiques eux-mêmes • Association des éléments graphiques à des classes et publication du fichier SWF de bibliothèque Création d’une classe pour implémenter l’interface RuntimeLibrary Nous allons ensuite créer la classe GeometricAssets qui implémente l’interface RuntimeLibrary, et sera la classe du document FLA. Le code de cette classe est très proche de celui de l’interface RuntimeLibrary, la différence étant que la définition de classe comporte le corps de la méthode getAssets(). package { import flash.display.Sprite; import com.example.programmingas3.runtimeassetexplorer.RuntimeLibrary; public class GeometricAssets extends Sprite implements RuntimeLibrary { public function GeometricAssets() { } public function getAssets():Array { return [ "com.example.programmingas3.runtimeassetexplorer.AnimatingBox", Pour les besoins de cet exemple, nous étendrons simplement la classe MovieClip, sans ajouter de fonctionnalité aux éléments. Le code suivant destiné à AnimatingStar est semblable à celui de AnimatingBox : package com.example.programmingas3.runtimeassetexplorer { import flash.display.MovieClip; public class AnimatingStar extends MovieClip { public function AnimatingStar() { } Nous allons maintenant relier les actifs de classe MovieClip à la nouvelle classe en créant un fichier FLA et en entrant GeometricAssets dans le champ Classe du document de l’Inspecteur des propriétés. Pour les besoins de cet exemple, nous allons créer deux formes très simples qui utilisent une interpolation de scénario pour effectuer une rotation horaire sur 360 images. Les deux symboles animatingBox et animatingStar sont définis pour l’exportation vers ActionScript et leurs champs Classe correspondent aux chemins de classe respectifs spécifiés dans l’implémentation de getAssets(). La classe de base par défaut flash.display.MovieClip est conservée, puisque nous voulons créer des sous-classes pour les méthodes MovieClip standard. Après définition des paramètres d’exportation de votre symbole, publiez le fichier FLA. Vous disposez maintenant de votre première bibliothèque d’exécution. Ce fichier SWF pourrait être chargé dans un autre fichier SWF AVM2, dans lequel les symboles AnimatingBox et AnimatingStar seraient disponibles.
Le dernier élément fonctionnel à traiter est l’interface utilisateur de l’explorateur. Dans cet exemple, le chemin d’accès à la bibliothèque d’exécution est codé en dur dans la variable ASSETS_PATH. Vous pourriez également utiliser la classe FileReference, par exemple pour créer une interface qui recherche un fichier SWF particulier sur le disque dur. Une fois que la bibliothèque d’exécution est chargée, Flash Player appelle la méthode runtimeAssetsLoadComplete(). private function runtimeAssetsLoadComplete(event:Event):void { var rl:* = event.target.content; var assetList:Array = rl.getAssets(); populateDropdown(assetList); stage.frameRate = 60; }
SWF chargé, obtient la liste des éléments disponibles et remplit un composant ComboBox avec cette liste en appelant la méthode populateDropDown(). Cette méthode enregistre le chemin de classe complet de chaque élément. Si l’utilisateur clique sur le bouton Ajouter, l’interface déclenche la méthode addAsset() : private { var var var ... } Dernière mise à jour le 27/4/2013
Ce chapitre est consacré à une autre technique de création d’une animation : l’interpolation de mouvement. Cette technique vous permet de créer un mouvement en le configurant en mode interactif dans un document par le biais d’Adobe® Flash® Professional. Vous pouvez ensuite utiliser ce mouvement dans votre animation dynamique à base de code ActionScript lors de l’exécution. Flash Professional génère automatiquement le code ActionScript qui implémente l’interpolation de mouvement et vous permet de le copier et de le réutiliser. Pour créer des interpolations de mouvement, vous devez disposer d’une licence pour Flash Professional.
Package fl.motion Les interpolations de mouvement permettent de créer aisément une animation. Une interpolation de mouvement modifie les propriétés d’un objet d’affichage, telles que la position ou la rotation, d’une image à l’autre. Elle permet également de modifier l’apparence d’un objet d’affichage en cours de déplacement en lui appliquant divers filtres et propriétés. Vous créez l’interpolation de mouvement en mode interactif dans Flash Professional, ce qui génère le code ActionScript correspondant. Dans Flash, utilisez la commande Copie de mouvement en tant qu’ActionScript 3.0 pour copier le code ActionScript à l’origine de l’interpolation de mouvement. Vous pouvez alors réutiliser le code ActionScript pour créer un mouvement dans votre animation dynamique lors de l’exécution. Pour plus d’informations sur la création d’une interpolation de mouvement, voir la section Interpolations de mouvement du manuel Utilisation de Flash Professional. Concepts importants et terminologie La liste de référence suivante contient un terme important relatif à la fonctionnalité étudiée : Interpolation de mouvement Construction qui génère des images intermédiaires d’un objet d’affichage dans des états
Une interpolation de mouvement permet de déplacer un objet d’affichage sur la scène, ainsi que de le faire progressivement grandir, rétrécir, pivoter ou changer de couleur.
Utilisation des interpolations de mouvement
Flash Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures, Flash CS3 ou ultérieur requis Une interpolation génère des images intermédiaires qui affichent un objet d’affichage dans des états différents dans deux images distinctes d’un scénario. Elle crée l’impression que le contenu de la première image se transforme progressivement en contenu de la seconde image. Dans une interpolation de mouvement, le changement d’apparence implique généralement la modification de la position de l’objet d’affichage, créant ainsi un mouvement. Outre le repositionnement de l’objet d’affichage, une interpolation de mouvement peut faire pivoter, incliner ou redimensionner ce dernier, voire lui appliquer des filtres. Vous créez une interpolation de mouvement dans Flash en déplaçant un objet d’affichage entre des images-clé du scénario. Flash génère automatiquement le code ActionScript qui décrit l’interpolation, que vous pouvez copier et enregistrer dans un fichier. Pour plus d’informations sur la création d’une interpolation de mouvement, voir la section Interpolations de mouvement du manuel Utilisation de Flash Professional. Vous pouvez accéder à la copie de mouvement en tant que commande ActionScript 3.0 dans Flash, de deux façons différentes. La première consiste à utiliser un menu contextuel d’interpolation sur la scène, comme suit : 1 Sélectionnez l’interpolation de mouvement sur la scène. 2 Cliquez dessus avec le bouton droit de la souris (Windows) ou cliquez sur la touche Contrôle (Macintosh). 3 Choisissez Copie de mouvement en tant que ActionScript 3.0 . . .
1 Sélectionnez l’interpolation de mouvement sur la scène.
Une fois le script copié, collez-le dans un fichier et enregistrez-le. Une fois l’interpolation de mouvement créée et après avoir copié et enregistré le script, vous pouvez la réutiliser sous sa forme actuelle ou la modifier dans votre propre animation dynamique pilotée par un script ActionScript.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures, Flash CS3 ou ultérieur requis L’en-tête du code ActionScript copié à partir de Flash recense tous les modules requis pour prendre en charge l’interpolation de mouvement.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures, Flash CS3 ou ultérieur requis Les classes principales d’interpolation de mouvement, AnimatorFactory, MotionBase et Motion, appartiennent au package fl.motion. Vous pourriez avoir besoin de classes supplémentaires suivant les propriétés que l’interpolation de mouvement manipule. Par exemple, si l’interpolation de mouvement transforme ou fait pivoter l’objet d’affichage, vous devez importer les classes flash.geom appropriées. Si des filtres sont appliqués, importez les classes flash.filter. Dans ActionScript, une interpolation de mouvement est une occurrence de la classe Motion. La classe Motion stocke une séquence d’animation d’images-clés pouvant s’appliquer à un objet visuel. Les données de l’animation comprennent les éléments suivants : position, échelle, rotation, inclinaison, couleur, filtres et accélération. Le code ActionScript suivant a été copié à partir d’une interpolation de mouvement créée dans Flash en vue d’animer un objet d’affichage portant le nom d’occurrence Symbol1_2. Il déclare une variable associée à un objet MotionBase nommé __motion_Symbol1_2. La classe MotionBase est le parent de la classe Motion.
Lorsque vous réutilisez un code ActionScript créé par Flash dans votre propre animation, vous pouvez conserver le nom d’interpolation automatiquement généré par Flash ou choisir un autre nom. Si vous modifiez le nom de l’interpolation, n’oubliez pas de répercuter la modification dans l’ensemble du script. Dans Flash, vous pouvez également affecter le nom de votre choix à l’objet cible de l’interpolation de mouvement, puis créer l’interpolation de mouvement et copier le script. Quelle que soit l’approche adoptée, assurez-vous que chaque objet Motion de votre code ActionScript possède un nom unique.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures, Flash CS3 ou ultérieur requis La méthode addPropertyArray() de la classe MotionBase ajoute un tableau de valeurs pour décrire chaque propriété interpolée. Le tableau contient potentiellement un élément par image-clé de l’interpolation de mouvement. Il arrive souvent que certains de ces tableaux contiennent moins d’éléments que le nombre total d’images-clés de l’interpolation de mouvement. Ce cas de figure se produit lorsque la dernière valeur du tableau n’est pas modifiée pour les images restantes. Si la longueur de l’argument array est supérieure à celle de la propriété duration de l’objet Motion, la méthode addPropertyArray() ajuste en conséquence la valeur de la propriété duration. Elle n’ajoute pas d’image-clé pour
Les propriétés x et y de l’objet Motion décrivent la nouvelle position de l’objet interpolé au fur et à mesure de l’exécution de l’animation. Ces coordonnées correspondent aux valeurs les plus susceptibles de changer dans chaque image-clé si la position de l’objet d’affichage évolue. La méthode addPropertyArray() vous permet d’ajouter d’autres propriétés de mouvement. Par exemple, ajoutez les valeurs scaleX et scaleY si l’objet interpolé est redimensionné. Ajoutez les valeurs skewX et skewY s’il est incliné. Ajoutez la propriété rotationConcat s’il fait l’objet d’une rotation. Utilisez la méthode addPropertyArray() pour définir les propriétés d’interpolation suivantes :
useRotationConcat Si cette propriété est définie, elle entraîne la rotation de l’objet cible lorsque la méthode addPropertyArray()
Le code suivant affecte des valeurs aux propriétés de l’interpolation de mouvement __motion_Wheel. Dans ce cas de figure, l’objet d’affichage interpolé ne change pas d’emplacement, mais pivote sur place dans les 29 images de l’interpolation de mouvement. Les diverses valeurs affectées au tableau rotationConcat définissent la rotation. Les autres valeurs de propriété de cette interpolation de mouvement ne sont pas modifiées. __motion_Wheel = new Motion(); __motion_Wheel.duration = 29; __motion_Wheel.addPropertyArray("x", [0]); Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures, Flash CS3 ou ultérieur requis Si l’objet cible d’une interpolation de mouvement contient des filtres, ces derniers sont ajoutés par le biais des méthodes initFilters() et addFilterPropertyArray() de la classe Motion.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures, Flash CS3 ou ultérieur requis La méthode initFilters() initialise les filtres. Son premier argument est un tableau qui recense les noms de classe entièrement qualifiés de tous les filtres appliqués à l’objet d’affichage. Ce tableau de noms de filtre est généré à partir de la liste de filtres associée à l’interpolation de mouvement dans Flash. Dans votre copie du script, vous pouvez supprimer ou ajouter dans ce tableau n’importe quel filtre du package flash.filters. L’appel suivant initialise la liste de filtres associée à l’objet d’affichage cible. Il applique les filtres DropShadowFilter, GlowFilter et BevelFilter et copie la liste dans chaque image-clé de l’objet Motion. __motion_Box.initFilters(["flash.filters.DropShadowFilter", "flash.filters.GlowFilter", "flash.filters.BevelFilter"], [0, 0, 0]);
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures, Flash CS3 ou ultérieur requis La méthode addFilterPropertyArray() décrit les propriétés d’un filtre initialisé doté des arguments suivants : 1 Son premier argument identifie un filtre en fonction de son index. L’index se réfère à la position du nom de filtre
2 Le deuxième argument est la propriété à stocker pour le filtre dans chaque image-clé. 3 Le troisième argument est la valeur de la propriété de filtre indiquée.
(index 0)du tableau de filtres initialisés : __motion_Box.addFilterPropertyArray(0, "blurX", [5]); Réglage de la couleur à l’aide de ColorMatrixFilter Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures, Flash CS3 ou ultérieur requis Une fois ColorMatrixFilter initialisé, vous pouvez définir les propriétés AdjustColor appropriées pour régler la luminosité, le contraste, la saturation et la teinte de l’objet d’affichage interpolé. En règle générale, le filtre AdjustColor est appliqué lors de la génération de l’interpolation de mouvement dans Flash. Vous pouvez l’ajuster dans votre copie du code ActionScript. L’exemple suivant transforme la teinte et la saturation de l’objet d’affichage au fur et à mesure qu’il se déplace. __motion_Leaf_1.initFilters(["flash.filters.ColorMatrix"], [0], -1, -1); __motion_Leaf_1.addFilterPropertyArray(0, "adjustColorBrightness", [0], -1, -1); __motion_Leaf_1.addFilterPropertyArray(0, "adjustColorContrast", [0], -1, -1); La classe AnimatorFactory gère l’association entre une interpolation de mouvement et ses objets d’affichage cible. L’argument du constructeur d’AnimatorFactory correspond à l’objet Motion : var __animFactory_Wheel:AnimatorFactory = new AnimatorFactory(__motion_Wheel);
IK, de sorte que les sections se déplacent avec réalisme. Les sections du squelette représentent ses os et articulations. A partir de l’extrémité finale du squelette, IK calcule les angles des articulations requises pour atteindre cette dernière. Calculer manuellement ces angles s’avérerait particulièrement complexe. Cette fonctionnalité présente l’avantage de permettre de créer des squelettes en mode interactif dans Adobe® Flash® Professional. Il vous suffit ensuite de les animer par le biais d’ActionScript. Le moteur IK intégré à Flash Professional exécute les calculs requis pour décrire le mouvement du squelette. Vous pouvez restreindre le mouvement à certains paramètres dans votre code ActionScript. La version Flash Professional CS5 de la cinématique inverse (IK) intègre à présent le concept de ressort de segment, généralement réservé aux applications d’animation haut de gamme. Associée au nouveau moteur physique dynamique, cette fonctionnalité permet de configurer des mouvements réalistes. Cet effet est par ailleurs visible lors des phases d’exécution et de création. Pour créer des squelettes de cinématique inverse, vous devez disposer d’une licence pour Flash Professional.
Package fl.ik La cinématique inverse (IK) vous permet de créer une animation réaliste en liant des sections de sorte qu’elles se déplacent les unes par rapport aux autres avec naturel. L’utilisation d’IK vous permet par exemple de déplacer une jambe pour qu’elle occupe une position déterminée en articulant les mouvements des articulations de la jambe nécessaires à l’obtention de la pose appropriée. IK utilise une structure osseuse chaînée portant le nom de squelette IK. Le package fl.ik vous aide à créer des animations qui ressemblent à un mouvement naturel. Il vous permet d’animer plusieurs squelettes IK en toute transparence sans avoir à maîtriser les concepts physiques sur lesquels s’appuient les algorithmes IK. Vous créez le squelette IK et les os et articulations qui le composent dans Flash Professional. Vous pouvez ensuite utiliser les classes IK pour les animer lors de l’exécution. Pour obtenir des instructions détaillées sur la création d’un squelette IK, voir Utilisation de la cinématique inverse dans Utilisation de Flash Professional.
La liste de référence suivante contient des termes importants relatifs à la fonctionnalité étudiée. Squelette Chaîne cinématique composée d’os et d’articulations, utilisée en animation informatique pour simuler un
Os Segment rigide d’un squelette, équivalent à un os chez un animal. Cinématique inverse (IK) Processus d’identification des paramètres d’un objet souple articulé appelé squelette ou Aperçu de l’animation de squelettes IK Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures, Flash CS4 ou ultérieur requis Une fois le squelette IK créé dans Flash Professional, utilisez les classes fl.ik pour restreindre ses mouvements, suivre les événements correspondants et l’animer lors de l’exécution. La figure ci-dessous illustre le clip Wheel. L’essieu est une occurrence d’un squelette IK appelée Axle. La classe IKMover déplace le squelette en le synchronisant avec la rotation d’une roue. Dans le squelette, IKBone, nommé ikBone2, est rattaché à la roue au niveau de l’articulation arrière.
• Instancie un objet IKMover. • Déplace l’essieu en conjonction avec la rotation de la roue. import fl.ik.* var var var var
Commencez par déclarer les variables associées au squelette, à l’os et à l’articulation qui composent les sections à déplacer. Le code suivant utilise la méthode getsqueletteByName() de la classe IKManager pour affecter la valeur du squelette Axle à la variable IKArmature tree. Le squelette Axle a été précédemment généré dans Flash Professional. var tree:IKArmature = IKManager.getArmatureByName("Axle");
IKBone la valeur de l’os ikBone2. var bone:IKBone = tree.getBoneByName("ikBone2");
La ligne suivante déclare la variable endEffector et l’affecte à la propriété tailjoint de l’os ikBone2 : var endEffector:IKJoint = home.tailjoint;
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures, Flash CS4 ou ultérieur requis Une occurrence de la classe IKMover déplace l’essieu. La ligne suivante instancie l’objet IKMover ik et transmet à son constructeur l’élément à déplacer et le point de départ du mouvement : var ik:IKMover = new IKMover(endEffector, pos);
Les propriétés de la classe IKMover vous permettent de restreindre le mouvement d’un squelette. Vous pouvez restreindre le mouvement en fonction de la distance, des itérations et de la durée du mouvement. Les paires de propriétés suivantes imposent ces restrictions. Les paires se composent d’une valeur booléenne qui indique si le mouvement est restreint et d’un entier stipulant la restriction : Propriété Boolean
L’objet IKMover déplace l’essieu au sein de l’écouteur d’événement associé à la roue. A chaque événement enterFrame de la roue, une nouvelle position cible du squelette est calculée. Par le biais de sa méthode moveTo(), l’objet IKMover place l’articulation arrière sur sa position cible ou parcourt une distance aussi longue que possible sans enfreindre les contraintes définies par ses propriétés limitByDistance, limitByIteration et limitByTime. Wheel.addEventListener(Event.ENTER_FRAME, frameFunc); function frameFunc(event:Event) { if (Wheel != null) { var mat:Matrix = Wheel.transform.matrix; var pt = new Point(90,0); pt = mat.transformPoint(pt); ik.moveTo(pt); Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures, Flash CS5 ou ultérieur requis La cinématique inverse prend en charge le ressort de segment dans Flash Professional CS5. Vous pouvez définir les ressorts de segment lors de la phase de création et ajouter ou modifier les attributs correspondants lors de l’exécution. La propriété Spring se rapporte à un segment et aux liaisons correspondantes. Elle possède deux attributs, IKJoint.springStrength, qui définit l’intensité du ressort, et IKJoint.springDamping, qui ajoute une résistance à la valeur d’intensité et modifie la valeur de décroissance du ressort. L’intensité du ressort est exprimée sous forme de pourcentage compris entre la valeur par défaut, 0 (rigidité absolue) et 100 (élasticité importante contrôlée par les lois de la physique). Les segments à ressort réagissent au mouvement de la liaison correspondante. Si aucune autre translation (rotation, x ou y) n’est activée, les paramètres du ressort n’ont aucun impact. L’amortissement du ressort est exprimé sous forme de pourcentage, compris entre la valeur par défaut, 0 (aucune résistance) et 100 (amortissement important). L’amortissement modifie la durée de l’intervalle qui sépare le mouvement initial d’un segment et son retour à une position de repos. Vérifiez si des ressorts sont associés à un objet IKArmature par le biais de la propriété IKArmature.springsEnabled. Les autres propriétés et méthodes relatives aux ressorts relèvent d’objets IKJoint individuels. Une liaison peut être soumise à une rotation angulaire et à une translation le long des axes x et y. Faites appel à IKJoint.setSpringAngle pour positionner l’angle de rotation d’un ressort de liaison et à IKJoint.setSpringPt pour définir la position par translation d’un ressort de liaison. Cet exemple sélectionne un segment par nom et identifie la propriété tailJoint correspondante. Le code teste le squelette parent pour vérifier si des ressorts sont activés, puis définit les propriétés du ressort de la liaison. var arm:IKArmature = IKManager.getArmatureAt(0); var bone:IKBone = arm.getBoneByName("c"); var joint:IKJoint = bone.tailJoint; if (arm.springsEnabled) { joint.springStrength = 50; //medium spring strength joint.springDamping = 10; //light damping resistance if (joint.hasSpringAngle) { joint.setSpringAngle(30); //set angle for rotational spring } }
11 et AIR 3 ou les versions ultérieures, vous pouvez effectuer le rendu de séquences 3D complexes à l’aide de l’API Stage3D. Une fenêtre d’affichage Stage3D n’est pas un objet d’affichage. Les graphiques 3D sont rendus dans une fenêtre d’affichage qui apparaît sous la liste d’affichage de Flash (et au-dessus de tous les plans de fenêtre d’affichage StageVideo). Plutôt que d’utiliser les classes DisplayObject de Flash pour créer une séquence, utilisez un processus 3D programmable (similaire à OpenGL et Direct3D). Ce processus prend les données et les textures comme entrées et effectue le rendu de la séquence à l’aide des programmes de shaders que vous fournissez. L’accélération matérielle est utilisée lorsqu’un processeur graphique (GPU) compatible disposant des pilotes pris en charge est disponible sur l’ordinateur client. Stage3D fournit une API de très bas niveau. Dans une application, vous êtes encouragé à utiliser une structure d’application 3D prenant en charge Stage3D. Vous pouvez créer votre propre structure d’application, ou utiliser l’une des nombreuses structures commerciales et Open Source déjà disponibles. Pour plus d’informations sur le développement d’applications 3D à l’aide de Stage3D et sur les structures d’application 3D disponibles, voir Flash Player Developer Center: Stage 3D.
La principale différence entre un objet en deux dimensions (2D) et un objet en trois dimensions (3D) projeté sur un écran en deux dimensions consiste en l’ajout d’une troisième dimension à l’objet. La troisième dimension permet à l’objet de se rapprocher et de s’éloigner du point de vue de l’utilisateur. Lorsque vous définissez explicitement la propriété z d’un objet d’affichage sur une valeur numérique, l’objet crée automatiquement une matrice de transformation 3D. Vous pouvez intervenir sur cette matrice pour modifier les paramètres de transformation 3D de l’objet. En outre, la rotation 3D diffère de la rotation 2D. En 2D, l’axe de la rotation est systématiquement perpendiculaire au plan x/y, autrement dit, elle se trouve sur l’axe z. En 3D, l’axe de rotation peut se trouver autour de n’importe lequel des axes, x, y ou z. La définition des propriétés de rotation et de mise à l’échelle d’un objet d’affichage lui permet de se déplacer dans l’espace 3D.
Travail en trois dimensions (3D)
La liste de référence suivante contient des termes importants utilisés dans le cadre de la programmation de graphiques en 3 dimensions : Perspective Dans un plan 2D, représentation de lignes parallèles convergeant vers un point de fuite pour donner une
Projection Génération d’une image 2D d’un objet 3D. La projection 3D mappe des points 3D sur un plan 2D. Rotation Modification de l’orientation (et souvent de la position) d’un objet en faisant décrire un mouvement
Transformation Modification de points 3D ou d’ensemble de points par translation, rotation, mise à l’échelle,
Translation Modification de la position d’un objet en déplaçant chacun de ses points sur une distance et dans une
Point de fuite Point auquel des lignes parallèles qui s’éloignent semblent se rencontrer lorsqu’elles sont représentées dans une perspective linéaire. Vecteur Un vecteur 3D représente un point ou un emplacement dans l’espace en trois dimensions à l’aide de
Sommet Point. Maillage texturé Tout point définissant un objet dans l’espace 3D. Mappage des coordonnées UV Mode d’application d’une texture ou d’une image bitmap à une surface 3D. Le mappage des coordonnées UV affecte des valeurs à des coordonnées sur une image en tant que pourcentages de l’axe horizontal (U) et de l’axe vertical (V). valeur T Facteur de mise à l’échelle permettant de déterminer la taille d’un objet 3D lorsque celui-ci se rapproche ou
Culling Rendu, ou non, des surfaces avec un enroulement spécifique. L’utilisation du culling (élimination) permet de
Dans les versions de Flash Player antérieures à Flash Player 10 et dans les versions d’Adobe AIR antérieures à Adobe AIR 1.5, les objets d’affichage possèdent deux propriétés, x et y, permettant de positionner ces derniers sur un plan 2D. A partir de Flash Player 10 et Adobe AIR 1.5, tout objet d’affichage ActionScript est doté d’une propriété z permettant de le positionner le long de l’axe z, qui est généralement utilisé pour indiquer la profondeur ou la distance. Flash Player 10 et Adobe AIR 1.5 prennent désormais en charge les effets 3D. Les objets 3D restent cependant essentiellement plats. Tout objet d’affichage, tel qu’un objet MovieClip ou Sprite, effectue en fait son propre rendu en deux dimensions, sur un plan unique. Les fonctions 3D vous permettent de placer, déplacer, faire pivoter et transformer de diverses façons ces objets planaires dans la totalité des trois dimensions. Elles vous permettent également de gérer les points 3D et de les convertir en coordonnées 2D (x et y), afin que vous puissiez projeter les objets 3D sur un affichage 2D. A l’aide de ces fonctions, vous pouvez simuler de nombreux types d’effets 3D.
ActionScript, la valeur de x augmente au fur et à mesure du déplacement vers la droite le long de l’axe x, et la valeur de y augmente au fur et à mesure du déplacement vers le bas le long de l’axe y. Le système de coordonnées 3D conserve ces conventions et ajoute un axe z dont la valeur augmente au fur et à mesure que vous vous éloignez du point de vue. A
1 La classe flash.display.DisplayObject contient la propriété z et de nouvelles propriétés de rotation et de mise à
DisplayObject.local3DToGlobal() simplifie la projection de géométrie 3D sur un plan 2D. 2 Vous pouvez utiliser la classe flash.geom.Vector3D en tant que structure de données pour la gestion des points 3D.
3 La classe flash.geom.Matrix3D prend en charge les transformations complexes de géométrie 3D, telles que la
4 La classe flash.geom.PerspectiveProjection contrôle les paramètres de mappage de géométrie 3D sur un affichage 2D.
1 Agencement et animation d’objets planaires dans l’espace 3D. Cette approche implique l’animation d’objets
DisplayObject.transform.matrix3D. L’objet DisplayObject.transform.perspectiveProjection personnalise le tracé des objets d’affichage dans la perspective 3D. Adoptez cette approche pour animer des objets 3D principalement composés de plans. Elle convient aux galeries d’image 3D ou aux objets d’animation 2D agencés dans l’espace 3D, par exemple.
Travail en trois dimensions (3D)
Pour convertir un objet d’affichage 2D en objet d’affichage 3D, vous devez explicitement définir sa propriété z sur une valeur numérique. Lorsque vous affectez une valeur à la propriété z, un objet Transform est créé pour l’objet d’affichage. La définition des propriétés DisplayObject.rotationX ou DisplayObject.rotationY crée également un objet Transform. Celui-ci contient une propriété Matrix3D qui régit la représentation de l’objet d’affichage dans l’espace 3D. Le code suivant définit les coordonnées d’un objet d’affichage appelé « leaf » (feuille) : leaf.x = 100; leaf.y = 50; leaf.z = -30;
Transform de la feuille : var leafMatrix:Matrix3D
Le code suivant modifie la valeur de la propriété z de deux ellipses en réponse à un événement pour leur imprimer un mouvement de va-et-vient le long de leur axe z. ellipse2 se déplace plus rapidement qu’ellipse1 : sa propriété z est incrémentée d’un multiple de 20 sur chaque événement Frame, alors que la propriété z d’ellipse1 est incrémentée d’un multiple de 10 :
Dans la figure suivante, la propriété rotationY du conteneur des carrés a été incrémentée pour les faire pivoter sur l’axe y. La rotation du conteneur, ou objet d’affichage parent, des deux carrés fait pivoter ceux-ci : container.rotationY += 10;
Un objet d’affichage peut se déplacer et pivoter simultanément dans l’espace 3D.
La classe PerspectiveProjection du package flash.geom facilite l’application d’une perspective rudimentaire lors du déplacement d’objets d’affichage dans l’espace 3D. Si vous ne créez pas explicitement une projection de perspective pour votre espace 3D, le moteur 3D utilise un objet PerspectiveProjection par défaut, qui existe sur la racine et est propagé à tous ses enfants. Les trois propriétés qui définissent le mode d’affichage de l’espace 3D par un objet PerspectiveProjection sont les suivantes :
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures En manipulant la propriété fieldOfView de la classe PerspectiveProjection, vous pouvez faire en sorte qu’un objet d’affichage 3D semble s’agrandir ou diminuer selon qu’il se rapproche ou s’éloigne de l’observateur, respectivement.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures La propriété projectionCenterreprésente le point de fuite de la projection de perspective. Elle est appliquée comme décalage du point d’alignement par défaut (0,0) dans l’angle supérieur gauche de la scène. A mesure qu’il semble s’éloigner de l’observateur, un objet s’incline vers le point de fuite et finit par disparaître. Imaginez un couloir extrêmement long. Lorsque vous regardez dans le couloir, les bords des murs convergent vers un point de fuite tout au fond. Si le point de fuite se trouve au centre de la scène, le couloir disparaît vers un point central. La valeur par défaut de la propriété projectionCenter correspond au centre de la scène. Si, par exemple, vous souhaitez que des éléments apparaissent sur la gauche de la scène et une zone 3D sur la droite de la scène, définissez la propriété projectionCenter sur un point situé dans la partie droite de la scène pour en faire le point de fuite de votre zone d’affichage 3D.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures La propriété focalLength représente la distance séparant l’origine du point de vue (0,0,0) de l’emplacement de l’objet d’affichage sur son axe z. Une distance focale élevée est similaire à un téléobjectif : le champ de vision est étroit et les distances entre les objets compressées. Une distance focale courte s’assimile à un objectif à grand angle et se caractérise par un champ de vision large et une distorsion prononcée. Une distance focale moyenne correspond approximativement à ce que voit l’œil humain. En règle générale, la propriété focalLength est recalculée dynamiquement pendant la transformation de perspective au fur et à mesure du déplacement de l’objet d’affichage, mais il est possible de la définir explicitement.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures L’objet PerspectiveProjection par défaut créé sur la racine possède les valeurs suivantes :
Cet exemple : 1 crée un sprite appelé center, un cercle avec une mire ; 2 affecte les coordonnées du sprite center à la propriété projectionCenter de la propriété perspectiveProjection de la propriété transform de la racine ;
Pour obtenir les fichiers d’application de cet exemple, voir www.adobe.com/go/learn_programmingAS3samples_flash_fr. Les fichiers d’application ProjectionDragger résident dans le dossier Samples/ProjectionDragger.
3D d’un espace de coordonnées sur un autre. Il n’est pas nécessaire de comprendre les mathématiques matricielles pour pouvoir utiliser la classe Matrix3D. Ses méthodes permettent de gérer la plupart des opérations de transformation courantes. Il est inutile de vous soucier de la définition explicite ou du calcul de la valeur de chaque élément de la matrice. Une fois la propriété z d’un objet d’affichage définie sur une valeur numérique, vous pouvez récupérer la matrice de transformation de l’objet par le biais de la propriété Matrix3D de l’objet Transform de l’objet d’affichage : var leafMatrix:Matrix3D = this.transform.matrix3D;
Utilisez la classe Vector3D et ses propriétés x, y et z pour gérer les points 3D. Elle peut également représenter en physique un vecteur spatial, doté d’une direction et d’une magnitude. Les méthodes de la classe Vector3D vous permettent d’effectuer des calculs courants portant sur des vecteurs spatiaux : somme, produit scalaire et produit vectoriel, par exemple. Remarque : la classe Vector3D n’a aucun rapport avec la classe Vector d’ActionScript. La classe Vector3D contient des propriétés et des méthodes permettant de définir et de manipuler les points 3D, alors que la classe Vector prend en charge les tableaux d’objets typés.
Vous pouvez créer ou récupérer des objets Matrix3D de trois façons principales :
Exemple : var rotateMatrix:Matrix3D = new Matrix3D(1,0,0,1, 0,1,0,1, 0,0,1,1, 0,0,0,1);
Vous pouvez appliquer simultanément de nombreuses transformations 3D à l’aide d’un objet Matrix3D. Ainsi, pour faire pivoter, mettre à l’échelle, puis déplacer un cube, vous pourriez appliquer trois transformations distinctes à chacun de ses points. Il est cependant beaucoup plus efficace de précalculer plusieurs transformations dans un même objet Matrix3D et d’appliquer une transformation matricielle unique à chacun des points.
Cependant, chaque définition d’une propriété de rotation ou de mise à l’échelle donne lieu à plusieurs calculs et entraîne la modification de plusieurs propriétés de l’objet d’affichage. Si votre code applique plusieurs fois des transformations complexes identiques à des objets d’affichage, enregistrez l’objet Matrix3D en tant que variable, puis réappliquez-le autant de fois que nécessaire.
Comme indiqué plus haut, l’ordre d’apparition des objets d’affichage dans la liste d’affichage détermine l’ordre d’apparition à l’affichage, quels que soient leurs axes z relatifs. Si votre animation transforme les propriétés d’objets d’affichage dans un ordre différent de celui de la liste d’affichage, l’ordre d’apparition des objets d’affichage ne correspondra peut-être pas à celui des axes z. Un objet qui devrait sembler plus éloigné de l’observateur risque donc d’apparaître devant un objet plus proche. Pour avoir la certitude que l’ordre d’apparition des objets d’affichage 3D correspond à leur profondeur relative, procédez comme suit : 1 A l’aide de la méthode getRelativeMatrix3D() de l’objet Transform, extrayez la profondeur relative (z-axes)
2 Supprimez les objets de la liste d’affichage à l’aide de la méthode removeChild(). 3 Triez les objets d’affichage en fonction de leurs valeurs d’axe z relatives. 4 Ajoutez à nouveau les enfants à la liste d’affichage en ordre inverse, par le biais de la méthode addChild().
Dans ActionScript, vous effectuez des transformations de bitmap à l’aide de la méthode Graphics.drawTriangles(), car les modèles 3D sont représentés par un ensemble de triangles dans l’espace. (Flash Player et AIR ne prennent néanmoins pas en charge une mémoire tampon de profondeur, car les objets d’affichage sont toujours essentiellement plats, ou 2D. Pour plus d'informations, voir « Présentation des objets d’affichage 3D dans les moteurs d’exécution de Flash Player et d’AIR » à la page 363.) La méthode Graphics.drawTriangles() est similaire à la méthode Graphics.drawPath(), en ce qu’elle accepte un ensemble de coordonnées pour tracer un tracé triangulaire. Pour vous familiariser avec l’utilisation de Graphics.drawPath(), voir « Tracés de dessin » à la page 244. La méthode Graphics.drawTriangles() utilise une propriété Vector.<Number> pour spécifier l’emplacement des points sur le tracé triangulaire : drawTriangles(vertices:Vector.<Number>, indices:Vector.<int> = null, uvtData:Vector.<Number> = null, culling:String = "none"):void
Exemple : graphics.beginFill(0xFF8000); graphics.drawTriangles( Lorsque vous utilisez le paramètre indices, gardez à l’esprit le fait que les valeurs indices représentent des index de point, pas des index en rapport direct avec les éléments du tableau vertices. En d’autres termes, un index du vecteur vertices tel qu’il est défini par indices correspond en fait à l’index réel divisé par 2. Pour le troisième point d’un vecteur vertices, par exemple, utilisez une valeur indices de 2, même si la première valeur numérique de ce point commence à l’index vectoriel 4. Par exemple, fusionnez deux triangles de sorte qu’ils aient en commun le bord diagonal, par le biais du paramètre indices : graphics.beginFill(0xFF8000); graphics.drawTriangles( Vector.<Number>([10,10, 100,10, 10,100, 100,100]), Vector.<int>([0,1,2, 1,3,2]));
Le nombre total de sommets passe donc de 6 (12 nombres) à 4 (8 nombres).
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures Les transformations de bitmap donnent une illusion de perspective ou « texture » à un objet en trois dimensions. Vous pouvez notamment distordre une bitmap en direction d’un point de fuite, afin que l’image semble diminuer à mesure qu’elle se rapproche de celui-ci. Vous pouvez aussi utiliser une bitmap en deux dimensions pour créer une surface sur un objet en trois dimensions, donnant ainsi l’impression qu’il possède une texture ou « enveloppe ».
Lorsque vous commencerez à manipuler les textures, vous souhaiterez utiliser le paramètre uvtData de drawTriangles(). Ce paramètre vous permet de définir le mappage des coordonnées UV pour les remplissages de bitmap. Le mappage des coordonnées UV est une méthode d’application d’une texture à des objets. Il repose sur deux valeurs, une valeur U horizontale (x) et une valeur V verticale (y). Ces valeurs sont basées sur des pourcentages et non sur des valeurs de pixels. 0 U et 0 V correspondent au coin supérieur gauche d’une image, 1 U et 1 V à son coin inférieur droit :
La méthode Graphics.drawTriangles() accepte également une information facultative pour les transformations tridimensionnelles : la valeur T. La valeur T de uvtData représente la perspective 3D ou, plus spécifiquement, le facteur d’échelle du sommet associé. Le mappage des coordonnées UVT ajoute une correction de perspective au mappage des coordonnées UV. Par exemple, si un objet de l’espace 3D est éloigné du point de vue de telle sorte qu’il semble mesurer 50 % de sa taille « d’origine », sa valeur T correspond à 0,5. Comme les objets de l’espace 3D sont représentés à l’aide de triangles, l’emplacement de ceux-ci le long de l’axe z détermine leur valeur T. L’équation qui représente la valeur T est la suivante : T = focalLength/(focalLength + z);
Travail en trois dimensions (3D)
BitmapData. La source de la classe ImageLoader (enregistrez ce code dans le fichier ImageLoader.as) se présente comme suit : package { import flash.display.* import flash.events.*; import flash.net.URLRequest; public class ImageLoader extends Sprite { public var url:String; public var bitmap:Bitmap; public function ImageLoader(loc:String = null) { if (loc != null){ url = loc; loadImage(); Dernière mise à jour le 27/4/2013
Le culling est un processus qui détermine quelles surfaces d’un objet en trois dimensions ne doivent pas être rendues par le moteur de rendu car elles ne sont pas visibles à partir du point de vue actuel. Dans l’espace 3D, la surface « arrière » d’un objet en trois dimensions n’est pas visible à partir du point de vue.
(élimination) garantit que Flash Player ou AIR rend votre objet 3D correctement. En outre, pour éviter les cycles de rendu superflus, il est parfois souhaitable que le moteur de rendu omette certains triangles. Soit un cube en rotation dans l’espace. A tout moment donné, vous ne voyez jamais plus de trois de ses faces car celles qui ne sont pas visibles font face à l’autre direction, de l’autre côté du cube. Comme ces faces ne sont pas visibles, il est inutile que le moteur de rendu les trace. Sans élimination (culling), Flash Player ou AIR rend les faces avant et arrière.
Travail en trois dimensions (3D)
TriangleCulling.NONE, TriangleCulling.POSITIVE et TriangleCulling.NEGATIVE. Ces valeurs sont fonction de la direction du tracé triangulaire définissant la surface de l’objet. L’API ActionScript qui permet de déterminer le culling considère comme acquis que tous les triangles orientés vers l’extérieur d’une forme 3D sont tracés dans le même sens. Le retournement d’une face de triangle entraîne un changement de direction du tracé. A ce point, il est possible de supprimer le triangle du rendu. Si la valeur de TriangleCulling est définie sur POSITIVE, les triangles dont le tracé a une direction positive (sens horaire) sont supprimés. Si la valeur de TriangleCulling est définie sur NEGATIVE, les triangles dont le tracé a une direction négative (sens antihoraire) sont supprimés. Dans le cas d’un cube, les surfaces orientées vers l’avant ont un tracé à la direction positive et les surfaces orientées vers l’arrière, un tracé à la direction négative.
TriangleCulling.NEGATIVE : container.graphics.drawTriangles(vertices, indices, uvtData, TriangleCulling.NEGATIVE);
TextField ou les classes Text Engine de Flash. Ces classes vous permettent de créer, d’afficher et de mettre en forme du texte. Vous pouvez également utiliser Text Layout Framework (TLF). Il s’agit d’une bibliothèque de composants basée sur les classes Flash Text Engine, mais conçue de manière à offrir une utilisation conviviale. Sur les périphériques mobiles, vous pouvez utiliser la classe StageText pour saisir du texte. Vous pouvez établir le contenu spécifique de champs de texte ou désigner la source du texte, puis en définir l’aspect. Vous pouvez également répondre aux événements utilisateur (saisie de texte ou clic sur un lien hypertexte). Les classes TextField et Flash Text Engine vous permettent d’afficher et de gérer le texte dans Flash Player et AIR. Vous disposez de la classe TextField pour créer des objets texte à des fins d’affichage et d’entrée. La classe TextField sert de base à d’autres composants texte tels que TextArea et TextInput. La classe TextFormat permet de définir la mise en forme de caractère et paragraphe des objets TextField et vous pouvez appliquer des feuilles de style en cascade (CSS) à l’aide de la propriété Textfield.styleSheet et de la classe StyleSheet. Vous pouvez affecter directement à un champ de texte un texte au format HTML, qui peut contenir des médias intégrés (clips, fichiers SWF, fichiers GIF, fichiers PNG et fichiers JPEG). Flash Text Engine (FTE), disponible à partir de Flash Player 10 et Adobe AIR 1.5, propose une prise en charge de bas niveau pour un contrôle sophistiqué des mesures de texte, de la mise en forme et du texte bidirectionnel. Il se caractérise également par un flux de texte optimisé et une prise en charge des langues enrichie. Bien que vous puissiez utiliser Flash Text Engine pour créer et gérer des éléments texte, il est essentiellement destiné à générer des composants de manipulation du texte et nécessite des compétences accrues en matière de programmation. Text Layout Framework, qui comprend un composant de manipulation du texte basé sur Flash Text Engine, facilite l’utilisation des fonctions avancées du nouveau moteur texte. TLF est une bibliothèque extensible reposant entièrement sur ActionScript 3.0. Vous pouvez utiliser le composant TLF existant ou utiliser la structure pour créer votre propre composant de texte. La classe StageText, disponible à partir d’AIR 3, fournit un champ de saisie de texte natif. Etant donné que ce champ est mis à disposition par le système d’exploitation du périphérique, il fournit l’expérience avec laquelle les utilisateurs d’un périphérique sont le plus familiarisés. Une occurrence de StageText n’est pas un objet d’affichage. Plutôt que de l’ajouter à la liste d’affichage, affectez une scène à une occurrence, ainsi qu’une zone d’affichage sur cette scène appelée fenêtre d’affichage. L’occurrence de StageText s’affiche face à tous les objets d’affichage. Pour plus d’informations, voir :
• « Utilisation de Flash Text Engine » à la page 410 • « Utilisation de Text Layout Framework » à la page 440 • Native text input with StageText (disponible en anglais uniquement)
Principes de base de l’utilisation du texte
La liste de référence suivante contient des termes importants relatifs à la manipulation du texte : Feuilles de style en cascade Syntaxe standardisée permettant de définir les styles et la mise en forme du texte structuré
Police de périphérique Police installée sur l’ordinateur de l’utilisateur. Champ de texte dynamique Champ de texte dont le contenu peut être modifié en ActionScript, mais pas par
Police incorporée Police de caractères dont les données, sous forme vectorielle, sont enregistrées dans le fichier SWF
Texte HTML Texte inséré dans un champ de texte en ActionScript qui, outre le contenu à proprement parler, comporte des balises HTML de mise en forme. Champ de saisie de texte Champ de texte dont le contenu peut être modifié soit en ActionScript, soit par l’utilisateur. Crénage Réglage de l’espace entre les paires de caractères de sorte à uniformiser l’espacement des mots et à améliorer
Champ de texte statique Champ de texte créé dans l’environnement de création, dont le contenu ne peut pas être modifié pendant l’exécution du fichier SWF. Métrique des lignes de texte Mesure de la taille des diverses parties du texte figurant dans un champ de texte : ligne
Interlettrage Réglage de l’espacement entre des groupes de lettres ou des blocs de texte en vue d’augmenter ou de
à l’écran dans Adobe® Flash® Player ou Adobe® AIR™. La classe TextField sert de base à d’autres composants de texte tels que TextArea ou TextInput. Le contenu des champs de texte peut être spécifié à l’avance dans le fichier SWF, chargé à partir d’un fichier texte ou d’une base de données, ou saisi par l’utilisateur dans votre application. Au sein du champ lui-même, le texte peut être du contenu HTML, avec des images incorporées. Après avoir créé une occurrence de champ de texte, vous pouvez utiliser les classes flash.text, telles que TextFormat et StyleSheet, pour contrôler l’aspect du texte. Le package flash.text contient la quasi-totalité des classes relatives à la création, à la gestion et au formatage de texte dans ActionScript. Pour mettre en forme du texte, il est nécessaire de créer un objet TextFormat et de l’affecter au champ de texte. Si le champ de texte contient du texte en HTML, vous pouvez lui appliquer un objet StyleSheet pour affecter des styles à des éléments spécifiques du texte. L’objet TextFormat ou StyleSheet contient des propriétés qui définissent l’aspect du texte, par exemple sa couleur, sa taille et sa graisse. L’objet TextFormat attribue des propriétés à l’ensemble du contenu d’un champ de texte, ou à une partie du texte seulement. Par exemple, au sein du même champ de texte, une phrase peut être en gras et en rouge, puis la suivante en italique et en bleu. Outre les classes du package flash.text, la classe flash.events.TextEvent permet de répondre aux actions de l’utilisateur liées au texte.
« Attribution de formats texte » à la page 393 « Affichage du texte HTML » à la page 387 « Application de feuilles de style en cascade » à la page 394
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Bien que les outils de programmation tels qu’Adobe Flash Builder et Flash Professional offrent plusieurs options d’affichage du texte (composants liés au texte ou outils texte), la méthode d’affichage de texte par programmation la plus simple consiste à utiliser un champ de texte.
Utilisation de la classe TextField
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le type de texte d’un champ de texte est caractérisé par sa source :
Le texte dynamique correspond au contenu chargé à partir d’une source externe, telles qu’un fichier texte ou xml, ou un service Web.
TextSnapshot pour manipuler une occurrence de texte statique existante. Pour plus d’informations, voir « Utilisation du texte statique » à la page 399.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous pouvez définir du texte dynamique en affectant une chaîne à la propriété flash.text.TextField.text. La chaîne est directement affectée à la propriété, comme suit : myTextField.text = "Hello World";
{ import flash.display.Sprite; import flash.text.*; public class TextWithImage extends Sprite { private var myTextBox:TextField = new TextField(); private var myText:String = "Hello World"; public function TextWithImage() La propriété htmlText de la classe flash.text.TextField permet d’indiquer que la chaîne de texte contient des balises HTML de formatage du contenu. Comme le montre l’exemple suivant, vous devez affecter votre chaîne à la propriété htmlText (et non à la propriété text) pour que Flash Player ou AIR puisse afficher le texte sous forme HTML : var myText:String = "<p>This is <b>some</b> content to <i>render</i> as <u>HTML</u> text.</p>"; myTextBox.htmlText = myText;
La description de propriété flash.text.TextField.htmlText dans le manuel Guide de référence ActionScript 3.0 pour Flash Professional fournit des informations détaillées sur les balises et entités HTML prises en charge. Une fois que vous avez spécifié votre contenu à l’aide de la propriété htmlText, vous pouvez utiliser des feuilles de style ou la balise textformat pour gérer le formatage. Pour plus d’informations, voir « Mise en forme du texte » à la page 393.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’affichage du contenu sous forme de texte HTML présente un autre avantage : vous pouvez inclure des images dans le champ de texte. Il est possible de référencer une image, locale ou distante, grâce à la balise img et de la faire apparaître dans le champ de texte associé. L’exemple suivant crée un champ de texte appelé myTextBox et incorpore au texte une image JPG représentant un œil, image stockée dans le même répertoire que le fichier SWF :
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Dans bien des cas, votre texte peut s’avérer plus long que le champ de texte qui le contient. Il se peut également qu’un champ de saisie permette à l’utilisateur de saisir plus de caractères qu’il ne peut en afficher en une seule fois. Les propriétés de défilement de la classe flash.text.TextField permettent de gérer du contenu long, que ce soit verticalement ou horizontalement. Ces propriétés sont les suivantes : TextField.scrollV, TextField.scrollH, maxScrollV et maxScrollH. Utilisezles pour répondre à des événements tels qu’un clic de souris ou une pression sur une touche. L’exemple ci-après crée un champ de texte de taille fixe et contenant plus de texte que le champ ne peut afficher en une seule fois. Lorsque l’utilisateur clique sur le champ de texte, le texte défile verticalement.
Vous pouvez sélectionner du texte, qu’il soit dynamique ou saisi. Les propriétés et méthodes de sélection de texte de la classe TextField utilisent des positions d’index pour déterminer l’étendue du texte à manipuler. Vous pouvez donc programmer la sélection du texte saisi ou dynamique, même si vous n’en connaissez pas le contenu. Remarque : si vous choisissez l’option sélectionnable associée à un champ de texte statique dans Flash Professional, le champ de texte exporté et placé dans la liste d’affichage est un champ de texte dynamique normal.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La propriété flash.text.TextField.selectable a la valeur true par défaut. Vous pouvez en outre sélectionner du texte par code à l’aide de la méthode setSelection(). Par exemple, pour sélectionner un texte spécifique dans un champ de texte lorsque l’utilisateur clique dans ce dernier : var myTextField:TextField = new TextField(); myTextField.text = "No matter where you click on this text field the TEXT IN ALL CAPS is selected."; myTextField.autoSize = TextFieldAutoSize.LEFT; addChild(myTextField); addEventListener(MouseEvent.CLICK, selectText); function selectText(event:MouseEvent):void { myTextField.setSelection(49, 65); }
Les propriétés selectionBeginIndex et selectionEndIndex de TextField, qui sont en lecture seule (et ne peuvent donc pas être utilisées à l’aide de code pour sélectionner du texte), permettent également de capturer la sélection actuelle effectuée par l’utilisateur. Par ailleurs, les champs de texte saisis peuvent utiliser la propriété caretIndex. Par exemple, ce code renvoie les valeurs d’index du texte sélectionné par l’utilisateur : var myTextField:TextField = new TextField(); myTextField.text = "Please select the TEXT IN ALL CAPS to see the index values for the first and last letters."; myTextField.autoSize = TextFieldAutoSize.LEFT; addChild(myTextField); addEventListener(MouseEvent.MOUSE_UP, selectText); function selectText(event:MouseEvent):void { trace("First letter index position: " + myTextField.selectionBeginIndex); trace("Last letter index position: " + myTextField.selectionEndIndex); } Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Par défaut, la propriété type d’un champ de texte est définie sur dynamic. Si vous attribuez à cette propriété type la valeur input à l’aide de la classe TextFieldType, vous pouvez recueillir la saisie de l’utilisateur et enregistrer cette valeur pour l’utiliser dans d’autres zones de l’application. Les champs de texte saisi sont utiles dans les formulaires et toute autre application qui attend que l’utilisateur définisse une valeur de texte à utiliser ailleurs dans le programme. Par exemple, le code suivant crée un champ de texte de saisie appelé myTextBox. Lorsque l’utilisateur saisit du texte dans le champ, l’événement textInput est déclenché. Un gestionnaire d’événement appelé textInputCapture capture la chaîne de texte saisie et l’attribue à une variable. Flash Player ou AIR affiche le nouveau texte dans un autre champ de texte appelé myOutputBox. package { import import import import
Les champs de texte de saisie sont souvent utilisés dans les formulaires et les boîtes de dialogue des applications. Il peut donc être judicieux de limiter le type de caractères que l’utilisateur peut saisir, ou même de masquer la saisie (pour un mot de passe par exemple). La classe flash.text.TextField possède une propriété displayAsPassword et une propriété restrict qui permettent de contrôler la saisie par l’utilisateur. La propriété displayAsPassword masque simplement le texte (en l’affichant sous forme d’astérisques) à mesure que l’utilisateur le saisit. Lorsque displayAsPassword a la valeur true, les commandes Couper et Copier, ainsi que les raccourcis clavier correspondants ne fonctionnent pas. Comme le montre l’exemple suivant, vous pouvez attribuer la propriété displayAsPassword, comme vous le feriez pour des propriétés d’arrière-plan et de couleur : myTextBox.type = TextFieldType.INPUT; myTextBox.background = true; myTextBox.displayAsPassword = true; addChild(myTextBox);
Mise en forme du texte Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Plusieurs options permettent de programmer la mise en forme du texte à afficher. Vous pouvez définir ses propriétés directement dans l’occurrence de TextField, par exemple TextFIeld.thickness, TextField.textColor et TextField.textHeight.Vous pouvez aussi désigner le contenu du champ de texte à l’aide de la propriété htmlText et utiliser des balises HTML prises en charge, telles que b, i et u. Vous pouvez enfin appliquer des objets TextFormat aux champs de texte contenant du texte brut, ou des objets StyleSheet aux champs contenant la propriété htmlText. Les objets TextFormat et StyleSheet offrent un meilleur contrôle et davantage de cohérence sur l’aspect du texte pour l’ensemble de l’application. Il est possible de définir un objet TextFormat ou StyleSheet et de l’appliquer à une partie ou à l’ensemble des champs de texte de l’application.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe TextFormat permet de définir différentes propriétés d’affichage du texte et de les appliquer à tout le contenu d’un objet TextField, ou à une plage de texte. L’exemple suivant applique un objet TextFormat à un objet TextField complet, puis un second objet TextFormat à une plage de texte de cet objet TextField : var tf:TextField = new TextField(); tf.text = "Hello Hello"; var format1:TextFormat = new TextFormat(); format1.color = 0xFF0000; var format2:TextFormat = new TextFormat(); format2.font = "Courier"; tf.setTextFormat(format1); var startRange:uint = 6; tf.setTextFormat(format2, startRange); addChild(tf);
TextField.setTextFormat() pour ré-appliquer la mise en forme. Vous pouvez également utiliser la propriété defaultTextFormat de TextField pour spécifier le format à utiliser pour le texte saisi par l’utilisateur.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les champs de texte peuvent contenir du texte brut ou du texte au format HTML. Le texte brut est stocké dans la propriété text de l’occurrence, et le texte HTML dans la propriété htmlText. Vous pouvez utiliser des déclarations de styles CSS pour définir des styles de texte à appliquer ensuite à différents champs de texte. Une déclaration de style CSS peut être créée par code ou chargée lors de l’exécution à partir d’un fichier CSS externe. C’est la classe flash.text.StyleSheet qui gère les styles CSS. La classe StyleSheet ne reconnaît qu’un nombre limité de propriétés CSS. La liste détaillée des propriétés de style prises en charge par la classe StyleSheet figure dans l’entrée flash.textStylesheet du Guide de référence ActionScript 3.0 pour Flash Professional. Comme le montre l’exemple suivant, vous pouvez créer des feuilles de style CSS et les appliquer à du texte HTML au moyen de l’objet StyleSheet : var style:StyleSheet = new StyleSheet(); var styleObj:Object = new Object(); styleObj.fontSize = "bold"; styleObj.color = "#FF0000"; style.setStyle(".darkRed", styleObj); var tf:TextField = new TextField(); tf.styleSheet = style; tf.htmlText = "<span class = 'darkRed'>Red</span> apple"; addChild(tf);
Pour que les styles CSS puissent prendre effet, il est nécessaire d’appliquer la feuille de style à l’objet TextField avant de définir la propriété htmlText. Par essence, un champ de texte doté d’une feuille de style n’est pas modifiable. Si vous attribuez une feuille de style à un champ de texte de saisie, le champ de texte affiche les propriétés de la feuille de style, mais le champ de texte ne permet pas à l’utilisateur de saisir du texte. En outre, vous ne pouvez pas utiliser les méthodes ActionScript suivantes sur un champ de texte doté d’une feuille de style :
Dernière mise à jour le 27/4/2013
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’utilisation de feuilles de style CSS pour la mise en forme offre plus de possibilités s’il est possible de charger les informations de CSS à partir d’un fichier externe lors de l’exécution. Si les données CSS sont externes à l’application, il est possible de changer le style visuel du texte sans devoir modifier le code source ActionScript 3.0. En effet, après le déploiement de l’application, vous pouvez encore modifier le fichier CSS externe pour obtenir un nouvel aspect, sans devoir redéployer le fichier SWF de l’application. La méthode StyleSheet.parseCSS() convertit une chaîne contenant des données CSS en déclarations de style dans l’objet StyleSheet. L’exemple suivant montre comment lire un fichier CSS externe et appliquer ses déclarations de style à un objet TextField. Voici le contenu du fichier CSS à charger. Il est appelé « example.css » : p { font-family: Times New Roman, Times, _serif; font-size: 14; } h1 { font-family: Arial, Helvetica, _sans; font-size: 20; font-weight: bold; } .bluetext { color: #0000CC; Formatage de plages de texte au sein d’un champ de texte Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe flash.text.TextField contient une méthode particulièrement utile, setTextFormat(). La méthode setTextFormat() permet d’affecter des propriétés spécifiques à une partie du contenu d’un champ de texte en réponse à une action de l’utilisateur, par exemple pour rappeler à l’utilisateur que certains champs d’un formulaire doivent être renseignés, ou encore pour changer l’aspect d’un passage de texte si l’utilisateur sélectionne une partie de ce texte. L’exemple suivant utilise la méthode TextField.setTextFormat() sur une plage de caractères pour modifier l’aspect d’une partie du contenu de myTextField lorsque l’utilisateur clique dans ce champ de texte : var myTextField:TextField = new TextField(); myTextField.text = "No matter where you click on this text field the TEXT IN ALL CAPS changes format."; myTextField.autoSize = TextFieldAutoSize.LEFT; addChild(myTextField); addEventListener(MouseEvent.CLICK, changeText); var myformat:TextFormat = new TextFormat(); myformat.color = 0xFF0000; myformat.size = 18; myformat.underline = true; function changeText(event:MouseEvent):void { myTextField.setTextFormat(myformat, 49, 65); } Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le package flash.text d’ActionScript 3.0 offre plusieurs classes qui permettent de contrôler les propriétés du texte affiché, notamment les polices intégrées, les paramètres d’anticrènelage, le canal alpha et autres paramètres spécifiques. Le Guide de référence ActionScript 3.0 pour Flash Professional fournit des descriptions détaillées de ces classes et de leurs propriétés, notamment des classes CSMSettings, Font et TextRenderer.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Si vous spécifiez une police précise pour un objet TextField de votre application, Flash Player ou AIR recherche une police résidente du même nom sur l’ordinateur de l’utilisateur. Si cette police n’est pas chargée sur cet ordinateur, ou s’il existe une police de ce nom mais dans une version légèrement différente, le texte peut apparaître très différent de ce que vous aviez prévu. Par défaut, le texte s’affiche dans la police Times Roman. Pour que l’utilisateur voie exactement la police voulue, vous pouvez incorporer cette police dans le fichier SWF de votre application. Les polices intégrées présentent de nombreux avantages :
• Il est possible de rendre transparent ou semi-transparent le texte des polices incorporées. • Il est possible d’utiliser le style CSS kerning (crénage) avec les polices incorporées. Le principal inconvénient des polices incorporées est l’augmentation de la taille du fichier de l’application. La méthode exacte à utiliser pour intégrer un fichier de police dans le fichier SWF de l’application varie selon l’environnement de développement. Une fois la police intégrée, il est possible de faire en sorte que l’objet TextField utilise la police correcte :
• Créez un objet TextFormat, donnez à sa propriété fontFamily le nom de la police incorporée, et appliquez l’objet TextFormat au TextField. Dans le cas d’une police incorporée, la propriété fontFamily ne doit contenir qu’un seul nom. Elle ne peut pas utiliser une liste de polices séparées par des virgules.
Intégration d’une police dans Flash Flash Professional vous permet d’intégrer pratiquement toutes les polices installées sur votre système, notamment les polices TrueType et les polices Postscript Type 1. Il existe plusieurs façons d’intégrer des polices dans une application. Vous pouvez par exemple :
Pour plus d’informations sur l’intégration de polices dans les applications, voir « Polices intégrées pour champs de texte dynamique ou de saisie » dans Utilisation de Flash. Intégration d’une police dans Flex Il existe plusieurs façons d’intégrer des polices dans une application Flex. Vous pouvez par exemple :
• utiliser la déclaration de style @font-face ; • définir la classe de la police et l’intégrer par le biais de la balise [Embed]. Seules les polices TrueType peuvent directement être intégrées dans une application Flex. Les polices dans un autre format, telles que les polices Postscript Type 1, doivent tout d’abord être intégrées dans un fichier SWF à l’aide de Flash Professional ; vous pouvez ensuite utiliser ce fichier SWF dans votre application Flex. Pour plus d’informations sur l’utilisation de polices intégrées dans Flex à partir de fichiers SWF, voir « Intégration de polices à partir de fichiers SWF » dans le manuel Utilisation de Flex 4.
Incorporation de polices pour assurer la cohérence de l’apparence du texte Peter deHaan : Embedding fonts (disponible en anglais uniquement) Divillysausages.com : AS3 Font embedding masterclass (disponible en anglais uniquement)
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Par défaut, Flash Player ou AIR détermine les paramètres de contrôle d’affichage du texte (netteté, épaisseur et anticrènelage) qui s’appliquent lorsque le texte change de taille et de couleur ou s’affiche sur différents arrière-plans. Dans certains cas, vous pouvez définir ces paramètres, par exemple si le texte est très petit ou très gros, ou s’il s’affiche sur plusieurs arrière-plans. La classe flash.text.TextRenderer et les classes associées, telles que CSMSettings, permettent de remplacer les paramètres de Flash Player ou d’AIR. Elles offrent un contrôle précis de la qualité d’affichage du texte incorporé. Pour plus d’informations sur les polices intégrées, voir « Utilisation de polices incorporées » à la page 397. Remarque : la propriété .antiAliasType de la classe flash.text.TextField doit avoir la valeur AntiAliasType.ADVANCED pour que vous puissiez définir la netteté, l’épaisseur ou la propriété gridFitType, ou pour que vous puissiez utiliser la méthode TextRenderer.setAdvancedAntiAliasingTable(). L’exemple suivant applique des propriétés personnalisées de modulation continue du trait (CSM) et de mise en forme au texte affiché, en utilisant la police incorporée myFont. Lorsque l’utilisateur clique sur le texte affiché, Flash Player ou Adobe AIR applique ces paramètres personnalisés :
ActionScript. Le texte statique est utile si le contenu textuel est court et ne doit pas changer (contrairement au texte dynamique). Vous pouvez assimiler le texte statique à un élément graphique comparable à un cercle ou un carré dessiné sur la Scène dans Flash Professional. Bien que le texte statique offre moins de possibilités que le texte dynamique, ActionScript 3.0 permet de lire les valeurs des propriétés du texte statique à l’aide de la classe StaticText. En outre, vous pouvez utiliser la classe TextSnapshot pour extraire des valeurs du texte statique.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous utilisez généralement la classe flash.text.StaticText dans le panneau Actions de Flash Professional pour agir sur une occurrence de texte statique placée sur la scène. Vous pouvez également travailler dans des fichiers ActionScript qui interagissent avec le fichier SWF contenant le texte statique. Dans les deux cas, il est impossible de créer par code une occurrence de texte statique. Le texte statique est créé dans Flash Professional. Pour créer une référence à un champ de texte statique existant, vous pouvez effectuer une itération sur les éléments de la liste d’affichage et affecter une variable. Exemple :
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour travailler par programmation avec une occurrence de texte statique existante, utilisez la classe flash.text.TextSnapshot pour modifier la propriété textSnapshot d’un objet flash.display.DisplayObjectContainer. En d’autres termes, créez une occurrence de TextSnapshot à partir de la propriété DisplayObjectContainer.textSnapshot. Vous pouvez alors appliquer des méthodes à cette occurrence afin d’extraire des valeurs ou de sélectionner des portions du texte statique. Par exemple, placez un champ de texte statique contenant le texte « TextSnapshot Example » sur la scène. Ajoutez le code ActionScript suivant à l’image 1 du scénario : var mySnap:TextSnapshot = this.textSnapshot; var count:Number = mySnap.charCount; mySnap.setSelected(0, 4, true); mySnap.setSelected(1, 2, false); var myText:String = mySnap.getSelectedText(false); trace(myText);
« article de journal » Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’exemple « Article de journal » met en forme le texte pour lui donner l’aspect d’un article de journal. Le texte saisi peut contenir un gros titre, un intertitre et le corps de l’article. En fonction d’une largeur et d’une hauteur d’affichage, cet exemple met en forme le gros titre et l’intertitre pour qu’ils occupent toute la largeur disponible. Le texte de l’article est réparti sur plusieurs colonnes. Cet exemple illustre les techniques de programmation en ActionScript suivantes :
• Chargement et application d’un fichier CSS externe • Conversion de styles CSS en objets TextFormat • Utilisation de la classe TextLineMetrics pour obtenir des informations sur la taille d’affichage du texte Pour obtenir les fichiers d’application de cet exemple, voir www.adobe.com/go/learn_programmingAS3samples_flash_fr. Les fichiers de l’application News Layout se trouvent dans le dossier Samples/NewsLayout. L’application se compose des fichiers suivants : Fichier
L’application News Layout commence par récupérer le texte de l’article à partir d’un fichier XML local. Elle lit ensuite un fichier CSS externe contenant les informations de mise en forme pour le gros titre, l’intertitre et le texte. Ce fichier CSS définit trois styles, un style de paragraphe standard pour l’article et les styles h1 et h2, respectivement pour le gros titre et l’intertitre.
Dernière mise à jour le 27/4/2013
Disposition des éléments de l’article sur la page Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe StoryLayout formate et met en page les champs de texte dévolus au gros titre, à l’intertitre et à l’article dans le style d’une page de journal. La méthode displayText() crée et place les divers champs.
Modification de la taille de la police en fonction de la taille du champ Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Sur la base d’une largeur en pixels et d’un nombre maximum de lignes à afficher, l’objet HeadlineTextField modifie la taille de la police pour adapter le texte aux dimensions du champ. Si le texte est court, la police est de grande taille, créant ainsi un gros titre de style tabloïde. Si le texte est long, la police est de plus petite taille. La méthode HeadlineTextField.fitText() reproduite ci-dessous est chargée du redimensionnement du texte :
Répartition du texte sur plusieurs colonnes Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe MultiColumnTextField répartit le texte entre plusieurs objets TextField qui sont organisés comme des colonnes de texte sur une page de journal. Le constructeur de MultiColumnTextField() crée tout d’abord un tableau d’objets TextField, un pour chaque colonne : for (var i:int = 0; i < cols; i++) { var field:TextField = new TextField(); field.multiline = true; field.autoSize = TextFieldAutoSize.NONE; field.wordWrap = true; field.width = this.colWidth; field.setTextFormat(this.format); this.fieldArray.push(field); this.addChild(field); }
Si la propriété text ou styleSheet de StoryLayout change, la méthode layoutColumns() est appelée pour réafficher le texte. La méthode layoutColumns() appelle la méthode getOptimalHeight() pour déterminer la hauteur correcte en pixels nécessaire pour adapter tout le texte en fonction de la largeur disponible.
TextLineMetrics.height représente la hauteur totale (en pixels) d’une ligne de texte, avec les mesures ascendantes, descendantes et l’interligne. La hauteur optimale de l’objet MultiColumnTextField est donc la hauteur de ligne multipliée par le nombre de lignes par colonne, plus 4 pour tenir compte de la bordure de deux pixels en haut et en bas de l’objet TextField. Voici le code complet de la méthode layoutColumns() : public function layoutColumns():void { if (this._text == "" || this._text == null) { return; } var field:TextField = fieldArray[0] as TextField; field.text = this._text; field.setTextFormat(this.format); this.preferredHeight = this.getOptimalHeight(field); var remainder:String = this._text; var fieldText:String = ""; var lastLineEndedPara:Boolean = true; var indent:Number = this.format.indent as Number; for (var i:int = 0; i < fieldArray.length; i++) Il se caractérise par un flux de texte optimisé et une prise en charge des langues enrichie. Bien qu’il puisse être utilisé pour créer et gérer de simples éléments de texte, FTE est l’outil de base pour les développeurs qui souhaitent créer des composants d’édition de texte. En tant que tel, Flash Text Engine nécessite des connaissances avancées en programmation. Pour afficher des éléments de texte simples, voir « Utilisation de la classe TextField » à la page 385. Text Layout Framework (TLF), qui comprend un composant de manipulation de texte basé sur FTE, propose une méthode d’utilisation de ses fonctions avancées plus conviviale. TLF est une bibliothèque extensible reposant entièrement sur ActionScript 3.0. Vous pouvez utiliser le composant TLF existant ou utiliser la structure pour créer votre propre composant de texte. Pour plus d’informations, voir « Utilisation de Text Layout Framework » à la page 440.
Package flash.text.engine Les classes qui constituent Flash Text Engine vous permettent de créer, de mettre en forme et de contrôler le texte. Les classes suivantes constituent les éléments de base pour la création et l’affichage de texte avec Flash Text Engine :
• ElementFormat : spécifie les attributs de mise en forme du contenu d’une occurrence de TextBlock • TextBlock : classe usine pour la création d’un paragraphe de texte • TextLine : ligne de texte créée à partir de TextBlock Pour afficher du texte, créez un objet TextElement à partir d’un élément String en utilisant un objet ElementFormat pour définir les caractéristiques de mise en forme. Affectez l’objet TextElement à la propriété content d’un objet TextBlock. Créez les lignes de texte à afficher en appelant la méthode TextBlock.createTextLine(). La méthode createTextLine() renvoie un objet TextLine qui contient le nombre de caractères de la chaîne correspondant à la largeur spécifiée. Appelez plusieurs fois la méthode jusqu’à ce que la chaîne entière s’affiche sous forme de lignes. Une fois toutes les lignes créées, la valeur TextLineCreationResult.COMPLETE est affectée à la propriété textLineCreationResult de l’objet TextBlock. Pour afficher les lignes, ajoutez-les à la liste d’affichage (associées aux valeurs de position x et y appropriées). Par exemple, le code suivant utilise ces classes FTE pour afficher « Hello World! This is Flash Text Engine! ».à l’aide du format et de la police par défaut. Dans cet exemple simple, une seule ligne de texte est générée.
Utilisation de Flash Text Engine
Vous pouvez remplacer du texte dans une occurrence de TextBlock en appelant la méthode TextElement.replaceText() en vue de remplacer le texte dans l’objet TextElement que vous avez affecté à la propriété TextBlock.content. L’exemple suivant utilise replaceText() pour d’abord insérer du texte au début de la ligne, puis pour ajouter du texte à la fin de la ligne et, enfin, pour remplacer du texte au milieu de la ligne. package { import flash.text.engine.*; import flash.display.Sprite; public class ReplaceTextExample extends Sprite { public function ReplaceTextExample() { var str:String = "Lorem ipsum dolor sit amet"; var fontDescription:FontDescription = new FontDescription("Arial"); var format:ElementFormat = new ElementFormat(fontDescription); format.fontSize = 14; var textElement:TextElement = new TextElement(str, format); var textBlock:TextBlock = new TextBlock(); textBlock.content = textElement; createLine(textBlock, 10); textElement.replaceText(0, 0, "A text fragment: "); createLine(textBlock, 30); textElement.replaceText(43, 43, "..."); createLine(textBlock, 50); textElement.replaceText(23, 28, "(ipsum)"); createLine(textBlock, 70); } function createLine(textBlock:TextBlock, y:Number):void { var textLine:TextLine = textBlock.createTextLine(null, 300); textLine.x = 10; textLine.y = y; addChild(textLine); Comme c’est le cas pour d’autres objets d’affichage, vous pouvez ajouter des écouteurs d’événement à une occurrence de TextLine. Par exemple, vous pouvez savoir à quel moment un utilisateur passe la souris sur une ligne de texte ou clique sur la ligne. L’exemple suivant détecte ces deux événements. Lorsque vous passez la souris sur une ligne, le curseur prend la forme d’un bouton et lorsque vous cliquez sur la ligne, il change de couleur. package { import import import import import
Un objet TextBlock est un objet usine pour la création de lignes de texte. Le contenu d’un objet TextBlock est affecté via l’objet TextElement. Un objet ElementFormat gère la mise en forme du texte. La classe ElementFormat définit certaines propriétés, telles que l’alignement sur la ligne de base, le crénage, l’interlettrage, la rotation du texte, la taille et la couleur des polices, ainsi que la casse. Elle comprend également la méthode FontDescription, décrite en détail à la section « Utilisation des polices » à la page 422.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures Le constructeur de l’objet ElementFormat prend des nombreux paramètres facultatifs, dont FontDescription. Vous pouvez également définir ces propriétés en dehors du constructeur. L’exemple suivant illustre la relation des différents objets lors de la définition et de l’affichage d’une ligne de texte simple :
La propriété color de l’objet ElementFormat définit la couleur de police. La valeur est un entier représentant les composants RVB de la couleur, par exemple : 0xFF0000 pour le rouge et 0x00FF00 pour le vert. La valeur par défaut est noir (0x000000). La propriété alpha définit la valeur de transparence alpha d’un élément (TextElement et GraphicElement). La plage des valeurs est comprise entre 0 (complètement transparent) et 1 (complètement opaque), qui est la valeur par défaut. Les éléments dont la propriété alpha est de 0 sont invisibles, mais restent actifs. Cette valeur est multipliée par l’une des valeurs alpha héritées, ce qui rend l’élément plus transparent. var ef:ElementFormat = new ElementFormat(); ef.alpha = 0.8; ef.color = 0x999999;
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures La police et la taille du plus grand texte dans une ligne déterminent sa ligne de base dominante. Vous pouvez écraser ces valeurs en définissant TextBlock.baselineFontDescription et TextBlock.baselineFontSize. Vous pouvez aligner la ligne de base dominante sur l’une des lignes de bases du texte, à savoir la ligne ascendante, la ligne descendante, ou la ligne de base idéographique supérieure, centrale ou inférieure.
La propriété baselineShift déplace la ligne de base selon un nombre de pixels défini sur l’axe y. Dans un texte normal (aucune rotation), une valeur positive déplace la ligne de base vers le bas et une valeur négative la déplace vers le haut.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures La propriété TypographicCase de l’objet ElementFormat spécifie la casse du texte : majuscule, minuscule ou petites capitales. var ef_Upper:ElementFormat = new ElementFormat(); ef_Upper.typographicCase = TypographicCase.UPPERCASE; var ef_SmallCaps:ElementFormat = new ElementFormat(); ef_SmallCaps.typographicCase = TypographicCase.SMALL_CAPS; Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures Vous pouvez appliquer une rotation au bloc de texte ou aux glyphes d’un segment de texte par incréments de 90°. La classe TextRotation définit les constantes suivantes pour définir la rotation du bloc de texte et des glyphes : Constante
Pour appliquer une rotation aux glyphes dans un bloc de texte ou un segment, définissez la propriété ElementFormat.textRotation sur le nombre de degrés de rotation des glyphes souhaité. Une glyphe est la forme qui constitue un caractère, ou une partie d’un caractère qui consiste en plusieurs glyphes. La lettre « a » et le point sur un « i », par exemple, sont des glyphes. La rotation des glyphes est importante dans certaines langues asiatiques, notamment si vous souhaitez appliquer une rotation verticale aux lignes, mais ne pas appliquer de rotation aux caractères dans les lignes. Pour plus d’informations sur la rotation du texte asiatique, voir « Justification du texte asiatique » à la page 426. Voici un exemple de rotation du texte et des glyphes qu’il contient dans un texte asiatique : Cet exemple utilise également une police japonaise : package { import flash.display.Sprite; import flash.text.*; public class RotationExample extends Sprite { private var tb:TextBlock = new TextBlock(); private var te:TextElement; private var ef:ElementFormat; private var fd:FontDescription = new FontDescription(); private var str:String; private var tl:TextLine; public function RotationExample() { fd.fontName = "MS Mincho"; ef = new ElementFormat(fd); ef.textRotation = TextRotation.AUTO; str = "This is rotated Japanese text"; te = new TextElement(str, ef); tb.lineRotation = TextRotation.ROTATE_90; tb.content = te; tl = tb.createTextLine(null,600); addChild(tl); IllegalOperationError. La meilleure pratique consiste à définir complètement ce type d’objet avant de l’affecter à l’occurrence de TextElement.
L’objet FontDescription est utilisé avec l’occurrence de ElementFormat pour identifier une police et définir certaines de ses caractéristiques. Ces caractéristiques incluent le nom de la police, le poids, la position, le rendu et la méthode de recherche de la police (police de périphérique/police intégrée). Remarque : FTE ne prend pas en charge les polices Type 1 ou les polices bitmap, telles que Type 3, ATC, CID ou CID basées sur SFNT.
La propriété fontName de l’objet FontDescription peut être un nom unique ou une liste de noms séparés par des virgules. Par exemple, dans une liste telle que « Arial, Helvetica, _sans », Text Engine recherche tout d’abord « Arial », puis « Helvetica » et finalement « _sans » s’il ne parvient pas à trouver les deux premières polices. La définition des noms de police comprend trois noms de police génériques : « _sans », « _serif » et « _typewriter ». Ces noms correspondent à des polices de périphérique spécifiques, selon le système de lecture. Il est judicieux de spécifier ce type de noms par défaut dans toutes les descriptions de police qui utilisent des polices de périphérique. Si la propriété fontName n’est pas spécifiée, « _serif » est utilisé comme nom par défaut. La propriété fontPosture peut être définie sur la valeur par défaut (FontPosture.NORMAL) ou en italique (FontPosture.ITALIC). La propriété fontWeight peut être définie sur la valeur par défaut (FontWeight.NORMAL) ou en caractères gras (FontWeight.BOLD). var fd1:FontDescription = new FontDescription(); fd1.fontName = "Arial, Helvetica, _sans"; fd1.fontPosture = FontPosture.NORMAL; fd1.fontWeight = FontWeight.BOLD;
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures La propriété fontLookup de l’objet FontDescription indique si Text Engine recherche une police de périphérique ou une police intégrée pour rendre le texte. Si une police de périphérique (FontLookup.DEVICE) est spécifiée, le moteur d’exécution recherche la police sur le système de lecture. Si vous définissez une police intégrée (FontLookup.EMBEDDED_CFF), le moteur d’exécution recherche une police de ce type portant le nom indiqué dans le fichier SWF. Seules les polices CFF (Compact Font Format) intégrées utilisent ce paramètre. Si la police spécifiée est introuvable, une police de périphérique est utilisée. Les polices de périphérique donnent lieu à des fichiers SWF moins volumineux. Les polices intégrées garantissent une plus grande homogénéité d’une plate-forme à l’autre. var fd1:FontDescription = new FontDescription(); fd1.fontLookup = FontLookup.EMBEDDED_CFF; fd1.fontName = "Garamond, _serif";
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures Le rendu CFF (Compact Font Format) est disponible à partir de Flash Player 10 et Adobe AIR 1.5. Ce type de rendu de police permet une meilleure lisibilité du texte et un affichage optimisé des caractères de petite taille. Ce paramètre s’applique uniquement aux polices intégrées. La valeur par défaut de FontDescription correspond à ce paramètre (RenderingMode.CFF) pour la propriété renderingMode. Vous pouvez définir cette propriété sur RenderingMode.NORMAL afin qu’elle corresponde au type de rendu utilisé par Flash Player 7 ou versions antérieures. Lorsque le rendu CFF est sélectionné, une deuxième propriété, cffHinting, permet de contrôler la manière dont les corps horizontaux d’une police sont adaptés à la grille de sous-pixels. La valeur par défaut, CFFHinting.HORIZONTAL_STEM, utilise les repères CFF. Si vous définissez cette propriété sur CFFHinting.NONE , les repères sont supprimés. Ce paramètre convient pour les animations ou les grandes tailles de police.
Si vous souhaitez modifier un objet FontDescription existant, vous devez tout d’abord vérifier sa propriété locked. Si elle est définie sur true, utilisez la méthode clone() pour créer une copie déverrouillée de l’objet. Vous pouvez modifier les propriétés de cet objet déverrouillé, puis l’affecter à ElementFormat. Toute nouvelle ligne créée à partir de ce TextElement adopte la nouvelle mise en forme. Les lignes précédentes créées à partir de ce même objet restent inchangées. package { import flash.display.Sprite; import flash.text.*; public class FontDescriptionCloneExample extends Sprite { private var tb:TextBlock = new TextBlock(); private var te:TextElement; private var ef1:ElementFormat; private var ef2:ElementFormat; private var fd1:FontDescription = new FontDescription(); private var fd2:FontDescription; public function FontDescriptionCloneExample() { fd1.fontName = "Garamond"; ef1 = new ElementFormat(fd); var str:String = "This is flash text"; te = new TextElement(str, ef); tb.content = te; var tx1:TextLine = tb.createTextLine(null,600); addChild(tx1); fd2 = (fd1.locked) ? fd1.clone() : fd1; fd2.fontName = "Arial"; ef2 = (ef1.locked) ? ef1.clone() : ef1; ef2.fontDescription = fd2; tb.content.elementFormat = ef2; var tx2:TextLine = tb.createTextLine(null,600); addChild(tx2); FTE vous propose un ensemble de commandes de mise en forme du texte afin de gérer la justification et l’espacement des caractères (crénage et interlettrage). Il existe également des propriétés permettant de détecter les lignes brisées et de définir des taquets de tabulation dans les lignes.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures En ajustant l’espacement entre les mots, et parfois entre les lettres, toutes les lignes d’un paragraphe possèdent une longueur identique. Bien que l’espacement entre les mots et les lettres varie, le texte est aligné des deux côtés. Les colonnes de texte dans les journaux et les magazines sont le plus souvent justifiées. La propriété lineJustfication de la classe SpaceJustifier vous permet de contrôler la justification des lignes dans un bloc de texte. La classe LineJustification définit des constantes en vue de spécifier une option de justification : ALL_BUT_LAST justifie tout le texte, à l’exception de la dernière ligne ; ALL_INCLUDING_LAST justifie tout le texte, y compris la dernière ligne ; l’option par défaut, UNJUSTIFIED, ne justifie pas le texte. Pour justifier le texte, définissez la propriété lineJustification sur une occurrence de la classe SpaceJustifier, puis affectez celle-ci à la propriété textJustifier d’une occurrence de TextBlock. L’exemple suivant crée un paragraphe dans lequel la totalité du texte est justifiée, à l’exception de la dernière ligne.
Pour justifier un texte asiatique, il faut tenir compte d’autres considérations. Le texte peut être écrit de haut en haut et certains caractères appelés kinsoku ne peuvent pas apparaître au début ou à la fin d’une ligne. La classe JustificationStyle définit les constantes suivantes, qui spécifient les options de gestion de ces caractères. PRIORITIZE_LEAST_ADJUSTMENT base la justification sur l’expansion ou sur la compression de la ligne, en fonction de celle qui produit les meilleurs résultats. PUSH_IN_KINSOKU base la justification sur la compression des caractères kinsoku à la fin de la ligne, ou sur l’expansion de la ligne s’il n’existe aucun caractère kinsoku ou si cet espace est insuffisant.
ElementFormat.textRotation sur TextRotation.AUTO (paramètre par défaut). Si vous définissez la propriété textRotation sur AUTO, les glyphes dans le texte restent verticales au lieu de pivoter sur le côté lors de la rotation de
à l’aide de l’option PUSH_IN_KINSOKU. package { import import import import
L’interlettrage ajoute ou soustrait un nombre de pixels défini entre les caractères dans un bloc de texte ; cet effet est également défini dans l’objet ElementFormat. L’interlettrage fonctionne avec les polices intégrées et les polices de périphérique. FTE prend en charge deux propriétés d’interlettrage : trackingLeft, qui ajoute ou soustrait des pixels à gauche d’un caractère, et trackingRight, qui ajoute ou soustrait des pixels à droite d’un caractère. Si vous utilisez le crénage, la valeur d’interlettrage est ajoutée aux valeurs de crénage ou soustraite des valeurs de crénage de chaque paire de caractères.
Unicode standard, telles que le saut entre les mots et sur les traits d’union. Le paramètre BreakOpportunity.ALL permet de considérer un caractère comme une opportunité de saut de ligne, ce qui est très utile lors de la création d’effets, tels que le texte le long d’un tracé. var ef:ElementFormat = new ElementFormat(); ef.breakOpportunity = BreakOpportunity.ALL;
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures Pour définir des taquets de tabulation dans un bloc de texte, définissez les taquets de tabulation en créant des occurrences de la classe TabStop. Les paramètres du constructeur TabStop() indiquent la méthode d’alignement du texte avec le taquet de tabulation. Ces paramètres indiquent la position du taquet de tabulation, et pour l’alignement décimal, la valeur d’alignement, exprimée sous forme de chaîne. En général, cette valeur est un point décimal, mais elle pourrait également être une virgule ou le symbole du dollar, du yen ou de l’euro, par exemple. La ligne de code suivante crée un taquet de tabulation appelé tab1. var tab1:TabStop = new TabStop(TabAlignment.DECIMAL, 50, ".");
TextBlock. Etant donné que la propriété tabStops nécessite un vecteur, créez tout d’abord un vecteur, puis ajoutez la tabulation pour l’arrêter. Le vecteur vous permet d’affecter un ensemble de taquets de tabulation au bloc de texte. L’exemple suivant crée une occurrence de Vector<TabStop> et lui ajoute un ensemble d’objets TabStop. Affectez ensuite les taquets de tabulation à la propriété tabStops d’une occurrence de TextBlock. var tabStops:Vector.<TabStop> = new Vector.<TabStop>(); tabStops.push(tab1, tab2, tab3, tab4); textBlock.tabStops = tabStops
L’exemple suivant illustre l’effet de chacune des options d’alignement de l’objet TabStop.
Cette page comprend un gros titre, un sous-titre et une section sur plusieurs colonnes. Créez d’abord un fichier FLA et rattachez le code suivant au cadre n° 2 de la couche par défaut : import com.example.programmingas3.newslayout.StoryLayout ; // frame sc ript - create a 3-columned arti cle layout var story:StoryLayout = new StoryLayout(720, 500, 3, 10); story.x = 20; story.y = 80; addChild(story); stop();
{ import flash.display.Sprite; import flash.text.StyleSheet; import flash.text.engine.*; import import import import import Dernière mise à jour le 27/4/2013
Text Layout Framework (TLF) est une bibliothèque ActionScript évolutive. TLF est basé sur le moteur texte d’Adobe® Flash® Player 10 et d’Adobe® AIR® 1.5. Il propose des fonctions typographiques et de mise en forme du texte avancées qui assurent une typographie innovatrice sur le Web. TLF peut être utilisé avec Adobe® Flex® ou Adobe® Flash® Professional. Les développeurs peuvent utiliser ou étendre des composants existants ou faire appel à la structure pour créer leurs propres composants texte. TLF intègre les fonctionnalités suivantes :
• Texte vertical, Tate-Chu-Yoko (texte horizontal placé entre du texte vertical) et justificateur pour la typographie asiatique
• API riches de développement destinées à manipuler le contenu, la mise en forme et le balisage de texte, ainsi qu’à créer des composants texte personnalisés
• Règles de positionnement et images intégrées Text Layout Framework est une bibliothèque ActionScript 3.0 basée sur la version de Flash Text Engine (FTE) introduite dans Flash Player 10. Vous pouvez accéder à FTE via le package flash.text.engine, qui fait partie intégrante de l’API (Application Programming Interface) de Flash Player 10. Toutefois, l’API de Flash Player fournit un accès de bas niveau à FTE, ce qui signifie que certaines tâches nécessitent parfois un volume de code relativement important. TLF encapsule le code de bas niveau dans des API simplifiées. Il propose également une architecture conceptuelle qui organise les blocs de construction de base définis par FTE pour former un système convivial. Contrairement à FTE, TLF n’est pas intégré à Flash Player. Il correspond à une bibliothèque de composants indépendants écrits entièrement en ActionScript 3.0. En raison de l’extensibilité de la structure, il peut être adapté à des environnements déterminés. Flash Professional et le kit de développement (SDK) de Flex contiennent tous deux des composants basés sur la structure TLF.
Utilisation de Text Layout Framework
• Arménien, cyrillique, éthiopien, géorgien et grec • Arabe et hébreu • Idéogrammes Han, Kana (chinois, coréen et japonais) et Hangul Johab (coréen) • Thaï, khmer et laotien • Bengali, dévanâgarî, gujarâtî, gourmoukhî, kannara, malayalam, oriya, tamoul, télougou et tibétain • Bouhid, chérokie, deseret, écriture syllabique canadienne, hanounoo, shavian, tagalog, tagbanoua, tifinaghe, vai et yi
Vous pouvez créer des composants personnalisés dans Flash directement à partir de classes TLF. Flash Professional CS5 intègre en outre une nouvelle classe, fl.text.TLFTextField, qui encapsule la fonctionnalité TLF. La classe TLFTextField permet de créer des champs de texte en ActionScript qui utilisent les fonctions d’affichage de texte avancées de TLF. Créez un objet TLFTextField à l’instar d’un champ de texte par le biais de la classe TextField. Utilisez ensuite la propriété textFlow pour appliquer le formatage avancé à partir des classes de TLF. Vous pouvez également créer l’occurrence de TLFTextField sur la scène à l’aide de l’outil texte de Flash Professional. Vous pouvez alors utiliser ActionScript pour contrôler le formatage et la mise en forme du champ de texte à l’aide de classes TLF. Pour plus d’informations, voir TLFTextField dans le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash. Dans Flex, utilisez les classes TLF. Pour plus d’informations, voir « Utilisation de Text Layout Framework » à la page 441.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures Si vous travaillez dans Flex ou créez des composants texte personnalisés, faites appel aux classes TLF. TLF est une bibliothèque ActionScript 3.0 entièrement intégrée à la bibliothèque textLayout.swc. La bibliothèque TLF contient environ 100 classes et interfaces ActionScript 3.0 réparties dans dix packages. Ces packages sont des sous-packages du package flashx.textLayout.
• Classes de rendu • Classes d’interaction utilisateur
Les packages suivants contiennent les classes de formatage et structures de données de TLF :
• flashx.textLayout.formats Les packages suivants contiennent les classes de rendu de TLF :
• flashx.textLayout.container La procédure suivante décrit le processus général de création de texte à l’aide de Text Layout Format : 1 Importez du texte formaté dans les structures de données TLF. Pour plus d’informations, voir « Structuration du
3 Associez le texte figurant dans les structures de données aux conteneurs et définissez les options de modification et
4 Créez un gestionnaire d’événement permettant de redistribuer le texte en réponse à des événements de
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures L’exemple suivant illustre la mise en forme d’une page de journal simple à l’aide de TLF. Cette page comprend un gros titre, un sous-titre et une section sur plusieurs colonnes : package { import import import import import import import import import import import
Dernière mise à jour le 27/4/2013
Le contrôleur est initialisé de sorte à définir le formatage, le défilement et autres options. Il contient la géométrie qui définit les limites du conteneur dans lequel est distribué le texte. Un objet TextLayoutFormat contient les options de formatage suivantes : hContainerFormat = new TextLayoutFormat();
La méthode resizeHandler() mesure l’espace disponible pour le rendu des conteneurs et affecte à ces derniers la taille appropriée. Un appel initial de la méthode compose() permet de calculer la hauteur appropriée du conteneur de gros titre. La méthode resizeHandler() peut alors placer et afficher le conteneur de gros titre par le biais de la méthode updateAllControllers(). Enfin, la méthode resizeHandler() se base sur la taille du conteneur de gros titre pour déterminer le positionnement du conteneur de corps de texte.
Exception faite du nœud racine, les éléments restants sont peu ou prou basés sur des éléments XHTML. Le schéma suivant illustre l’arborescence de la structure :
TLF Markup assure la représentation du texte la plus fidèle dans une arborescence TextFlow. Le langage de balisage associe des balises à chaque élément de base de l’arborescence TextFlow et fournit également des attributs pour toutes les propriétés de formatage intégrées à la classe TextLayoutFormat. Le tableau suivant dresse la liste les balises dont vous disposez dans TLF Markup. Elément
Les classes ListElement et ListItemElement permettent d’ajouter des listes à puce aux contrôles de texte. Il est possible d’imbriquer les listes à puce et de les personnaliser en vue d’utiliser plusieurs puces (ou marqueurs), ainsi que la numérotation automatique et la numérotation de style contour. Pour créer des listes dans un enchaînement, utilisez la balise <list>. Vous utilisez ensuite les balises <li> au sein de la balise <list> pour chaque élément de la liste. La classe ListMarkerFormat permet de personnaliser l’aspect des puces. L’exemple suivant crée des listes simples : <flow:list paddingRight="24" paddingLeft="24"> <flow:li>Item 1</flow:li> <flow:li>Item 2</flow:li> Dernière mise à jour le 27/4/2013
La largeur totale d’un élément correspond à la somme de la largeur de son contenu et des propriétés paddingLeft et paddingRight. La hauteur totale d’un élément correspond à la somme de la hauteur de son contenu et des propriétés paddingTop et paddingBottom. La marge correspond à l’espace qui sépare la bordure du contenu. Les propriétés de marge sont paddingBottom, paddingTop, paddingLeft et paddingRight. Il est possible d’appliquer un remplissage à l’objet TextFlow, ainsi qu’aux éléments enfants suivants :
• img Les valeurs valides des propriétés de remplissage sont un numéro (en pixels), « auto » et « inherit ». La valeur par défaut est « auto », qui signifie que la marge est automatiquement calculée et définie sur 0 pour tous les éléments, à l’exception de ListElement. Pour les objets ListElement, « auto » est défini sur 0, à l’exception du côté début de la liste, qui utilise la valeur de la propriété listAutoPadding. La valeur par défaut de listAutoPadding est de 40, qui donne aux listes un retrait par défaut. Les propriétés de marge n’héritent par défaut d’aucune valeur. Les valeurs « auto » et « inherit » sont des constantes définies par la classe FormatValue. Les propriétés de marge peuvent être des valeurs négatives.
Padding changes in TLF 2.0 (disponible en anglais uniquement) L’interface ITextLayoutFormat rassemble tous les formats susceptibles d’être appliqués à un objet FlowElement. Certains formats s’appliquent à un paragraphe de texte ou conteneur entier mais pas, en toute logique, à des caractères individuels. Ainsi, les formats tels que la justification et les taquets de tabulation s’appliquent à des paragraphes entiers, mais pas à des caractères individuels.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures Vous pouvez affecter des formats à tout objet FlowElement par le biais de propriétés. La classe FlowElement implémente l’interface ITextLayoutFormat, c’est pourquoi toute sous-classe de la classe FlowElement doit également implémenter cette interface. Ainsi, le code suivant illustre l’affectation de formats individuels à une occurrence de ParagraphElement : var p:ParagraphElement = new ParagraphElement(); p.fontSize = 18; p.fontFamily = "Arial";
Vous pouvez appliquer des formats à un objet FlowElement à l’aide de la classe TextLayoutFormat. Cette classe permet de créer un objet de formatage spécial qui contient toutes les valeurs de formatage requises. Vous pouvez ensuite affecter cet objet à la propriété format de n’importe quel objet FlowElement. Les classes TextLayoutFormat et FlowElement implémentent toutes deux l’interface ITextLayoutFormat. Cette caractéristique garantit que les deux classes contiennent les mêmes propriétés de format. Pour plus d’informations, voir TextLayoutFormat dans le manuel Guide de référence ActionScript 3.0 pour la plateforme Adobe Flash.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures Les formats sont hérités par le biais de l’arborescence d’enchaînements. Si vous affectez une occurrence de TextLayoutFormat à une occurrence de FlowElement possédant des enfants, la structure déclenche un processus appelé cascade. Dans le cadre d’une cascade, la structure examine de manière récursive chaque nœud de la hiérarchie qui hérite de valeurs de l’objet FlowElement. Elle détermine ensuite s’il est nécessaire d’affecter les valeurs héritées à chaque propriété de formatage. La cascade est définie par les règles suivantes : 1 Les valeurs des propriétés sont héritées uniquement d’un ancêtre proche (appelé également le parent). 2 Les valeurs des propriétés sont héritées uniquement si la propriété ne possède aucune valeur (en d’autres termes, la
3 Certains attributs non définis n’héritent d’une valeur que si la valeur de l’attribut est définie sur « inherit » ou sur
Par exemple, si vous définissez la valeur fontSize au niveau du flux TextFlow, ce paramètre s’applique à tous les éléments du flux TextFlow. En d’autres mots, les valeurs sont propagées en cascade vers le bas de l’arborescence d’enchaînements. Vous pouvez cependant remplacer la valeur d’un élément donné en lui affectant directement une nouvelle valeur. A titre de contre-exemple, si vous définissez la valeur backgroundColor au niveau TextFlow, les enfants du flux TextFlow n’en héritent pas. La propriété backgroundColor n’hérite en effet jamais de ses parents au cours d’une cascade. Vous pouvez éviter ce comportement en définissant la propriété backgroundColor de chaque enfant sur la valeur flashx.textLayout.formats.FormatValue.INHERIT.. Pour plus d’informations, voir TextLayoutFormat dans le manuel Guide de référence ActionScript 3.0 pour la plateforme Adobe Flash.
La classe TextConverter du package flashx.textLayout.conversion.* permet d’importer du texte dans TLF et d’en exporter hors de ce dernier. Utilisez cette classe si vous envisagez de charger du texte lors de l’exécution au lieu de le compiler dans le fichier SWF. Cette classe sert également à exporter du texte stocké dans une occurrence de TextFlow dans un objet String ou XML.
Les classes intégrées au package flashx.textLayout.conversion sont d’une souplesse considérable en ce qui concerne l’emplacement de stockage du texte. Ainsi, si vous stockez le texte dans une base de données, vous pouvez l’importer dans la structure pour l’afficher. Grâce aux classes du package flashx.textLayout.edit, vous pouvez alors modifier le texte et réexporter le texte modifié dans la base de données. Pour plus d’informations, voir flashx.textLayout.conversion dans le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash.
Une fois le texte stocké dans les structures de données TLF, Flash Player peut l’afficher. Le texte stocké dans l’arborescence d’enchaînements doit être converti dans un format géré par Flash Player. TLF propose deux méthodes de création d’objets d’affichage à partir d’un enchaînement. La première approche, plus simple, est adaptée à l’affichage de texte statique. La seconde, plus complexe, permet de créer du texte dynamique qui peut être sélectionné et modifié. Dans les deux cas, le texte est finalement converti en occurrences de la classe TextLine, qui fait partie du package flash.text.engine de Flash Player 10.
L’approche simple exploite la classe TextFlowTextLineFactory, qui se trouve dans le package flashx.textLayout.factory. L’avantage de cette approche, hormis sa simplicité, est qu’elle limite l’encombrement mémoire par rapport à l’approche FlowComposer. Il est recommandé d’y faire appel pour le texte statique que l’utilisateur ne doit ni modifier, ni sélectionner, ni faire défiler. Pour plus d’informations, voir TextFlowTextLineFactory dans le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash.
Un compositeur d’enchaînements permet de mieux contrôler l’affichage du texte que la classe TextFlowTextLineFactory. Grâce à un compositeur d’enchaînements, les utilisateurs peuvent, par exemple, sélectionner et modifier le texte. Pour plus d’informations, voir « Activation de la sélection, de la modification et de l’annulation de texte à l’aide de TLF » à la page 453. Un compositeur d’enchaînements est une occurrence de la classe StandardFlowComposer du package flashx.textLayout.compose. Il gère la conversion d’éléments TextFlow en occurrences de TextLine, ainsi que l’insertion de ces occurrences dans un ou plusieurs conteneurs. TextFlow
Un conteneur est une occurrence de la classe Sprite, qui est une sous-classe de la classe DisplayObjectContainer. Ces deux classes font partie intégrante de l’API de liste d’affichage Flash Player. Un conteneur est une forme plus avancée du rectangle de sélection utilisé par la classe TextLineFactory. A l’instar du rectangle de sélection, un conteneur circonscrit la zone dans laquelle s’affichent les occurrences de TextLine. A l’encontre d’un rectangle de sélection, à chaque conteneur correspond un objet de « contrôleur ». Le contrôleur gère le défilement, la composition, la liaison, le formatage et la gestion des événements à l’intention d’un conteneur ou d’un ensemble de conteneurs. A chaque conteneur correspond un objet de contrôleur, qui est une occurrence de la classe ContainerController du package flashx.textLayout.container. Pour afficher du texte, créez un objet de contrôleur destiné à gérer le conteneur et associez-le au compositeur d’enchaînements. Une fois le conteneur associé, composez le texte pour pouvoir l’afficher. Les conteneurs gèrent donc deux états, composition et affichage. La composition correspond au processus de conversion du texte issu de l’arborescence d’enchaînements en occurrences de TextLine, et de calcul de la position de ces occurrences dans le conteneur. L’affichage correspond au processus de mise à jour de la liste Flash Player. Pour plus d’informations, voir IFlowComposer, StandardFlowComposer et ContainerController dans le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash.
La possibilité de sélectionner ou modifier du texte est contrôlée au niveau de l’enchaînement. Chaque occurrence de la classe TextFlow est associée à un gestionnaire d’interaction. Vous pouvez accéder au gestionnaire d’interaction d’un objet TextFlow par le biais de la propriété TextFlow.interactionManager de ce dernier. Pour activer la sélection de texte, affectez une occurrence de la classe SelectionManager à la propriété interactionManager. Pour activer la sélection et la modification du texte, affectez une occurrence de la classe EditManager à la place d’une occurrence de la classe SelectionManager. Pour annuler une opération; créez une occurrence de la classe UndoManager et spécifiezla en tant qu’argument lorsque vous appelez le constructeur associé à EditManager. La classe UndoManager gère un historique des activités de modification les plus récentes de l’utilisateur et autorise ce dernier à annuler ou rétablir des modifications spécifiques. Ces trois classes font partie du package de modification. Pour plus d’informations, voir SelectionManager, EditManager et UndoManager dans le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash.
Les objets TextFlow distribuent des événements dans de nombreuses circonstances, à savoir :
• Propriété float de la classe InlineGraphicElement • Propriété clearFloats de la classe FlowElement La propriété float contrôle le positionnement du graphique et du texte qui l’entoure. La propriété clearFloats contrôle le positionnement des éléments du paragraphe par rapport à l’élément flottant. Pour contrôler l’emplacement d’une image dans un élément de texte, vous disposez de la propriété float. L’exemple suivant insère une image dans un paragraphe et l’aligne à gauche de sorte que le texte l’habille sur la droite : <flow:p paragraphSpaceAfter="15" >Images in a flow are a good thing. For example, here is a float. It should show on the left: <flow:img float="left" height="50" width="19" source="../assets/bulldog.jpg"></flow:img> Don't you agree? Another sentence here. Another sentence here. Another sentence here. Another sentence here. Another sentence here. Another sentence here. Another sentence here. Another sentence here.</flow:p>
La propriété clearFloats s’avère utile lorsque vous souhaitez ajuster la position de départ des paragraphes suivants qui habilleraient normalement l’image. Supposons, par exemple, que la largeur d’une image excède celle du premier paragraphe. Pour s’assurer que le deuxième paragraphe débute après l’image, définissez la propriété clearFloats. L’exemple suivant utilise une image dont la hauteur excède celle du texte dans le premier paragraphe. Pour que le deuxième paragraphe débute après l’image dans le bloc de texte, cet exemple définit la propriété clearFloats associée au deuxième paragraphe sur « end ». <flow:p paragraphSpaceAfter="15" >Here is another float, it should show up on the right: <flow:img float="right" height="50" elementHeight="200" width="19" source="../assets/bulldog.jpg"></flow:img>We'll add another paragraph that should clear past it.</flow:p><flow:p clearFloats="end" >This should appear after the previous float on the right.</flow:p>
ClearFloats définit ces constantes. Vous pouvez également définir la propriété clearFloats sur « inherit » (constante définie par la classe FormatValue). La valeur par défaut est « none ».
à l’interface utilisateur d’une application, ou même créer un programme qui analyse des fichiers mp3 chargés sur Internet, avec du son au coeur de l’application. Vous pouvez charger des fichiers audio externes et manipuler l’audio incorporé à un fichier SWF. Vous pouvez contrôler l’audio, créer des représentations visuelles des informations de son et capturer le son du microphone d’un utilisateur.
Package flash.media flash.events.SampleDataEvent Les ordinateurs peuvent capturer et coder l’audio numérique (représentation des informations de son de l’ordinateur), le stocker et le récupérer pour le diffuser sur des hauts-parleurs. Il est possible de lire le son à l’aide d’Adobe® Flash® Player ou Adobe® AIR™ et ActionScript. Lorsque les données audio sont converties au format numérique, elles possèdent différentes caractéristiques (volume du son, son stéréo ou mono). Lorsque vous lisez un son dans ActionScript, vous pouvez régler ces caractéristiques également (augmenter le volume du son ou faire comme s’il provenait d’une certaine direction, par exemple). Avant de contrôler un son dans ActionScript, les informations de son doivent être chargées dans Flash Player ou AIR. Vous disposez de cinq techniques de chargement des données audio dans Flash Player ou AIR afin de les utiliser avec ActionScript.
• Vous pouvez incorporer directement les informations audio dans le fichier SWF lors de sa création. • Vous pouvez capturer l’audio à partir d’un microphone connecté à l’ordinateur d’un utilisateur. • Vous pouvez diffuser l’audio en continu à partir d’un serveur. • Vous pouvez générer et lire l’audio en mode dynamique. Lorsque vous chargez des données audio depuis un fichier de son externe, vous pouvez commencer par lire le début du fichier audio pendant le chargement du reste des données audio. Même s’il existe différents formats de fichier audio utilisés pour coder l’audio numérique, ActionScript 3.0, Flash Player et AIR prennent en charge les fichiers audio stockés au format mp3. Ils ne peuvent pas charger ni lire directement des fichiers audio de formats différents (WAV ou AIFF, par exemple).
Vous pouvez également utiliser d’autres classes pour effectuer des tâches plus spécifiques lorsque vous utilisez du son dans ActionScript. Pour plus d’informations sur toutes les classes liées au son, voir « Présentation de l’architecture audio » à la page 456. Concepts importants et terminologie La liste de référence suivante contient des termes importants que vous rencontrerez peut-être : Amplitude Distance d’un point sur la courbe audio à partir de la ligne zéro ou d’équilibre. Débit Quantité de données codées ou diffusées en continu pour chaque seconde d’un fichier audio. Pour les fichiers
Mise en mémoire tampon Réception et stockage de données audio avant leur lecture. MP3 MPEG-1 Audio Layer 3, ou MP3, est un format de compression audio connu. Balance horizontale Positionnement d’un signal audio entre les canaux gauche et droit dans un champ acoustique
Crête Point le plus élevé d’une courbe audio. Fréquence d’échantillonnage Définit le nombre d’échantillons par seconde extraits d’un signal audio analogique pour échantillons par seconde. Diffusion en continu Processus consistant à lire les premières sections d’un fichier audio ou vidéo pendant le
Volume Intensité d’un son. Courbe audio Forme d’un graphique des différentes amplitudes d’un signal audio au cours du temps.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vos applications peuvent charger des données audio à partir de cinq sources principales :
• Ressources audio incorporées dans le fichier SWF de l’application • Données audio issues d’un microphone connecté au système de l’utilisateur • Données audio diffusées en continu depuis une passerelle multimédia telle que Flash Media Server
• Données audio générées dynamiquement par le biais du gestionnaire d’événement sampleData Vous pouvez charger entièrement les données audio avant leur lecture, ou bien les lire pendant leur chargement. ActionScript 3.0 prend en charge les fichiers audio stockés au format mp3. Ils ne peuvent pas charger ni lire directement des fichiers audio de formats différents, tels que WAV ou AIFF. Cependant, à partir de Flash Player 9.0.115.0, les fichiers audio AAC peuvent être chargés et lus à l’aide de la classe NetStream. Il s’agit de la même technique que celle utilisée pour le chargement et la lecture de contenu vidéo. Pour plus d’informations sur cette technique, voir « Utilisation de la vidéo » à la page 489. Vous pouvez utiliser Adobe Flash Professional pour importer des fichiers audio WAV ou AIFF puis les intégrer dans les fichiers SWF de votre application au format mp3. L’outil de programmation Flash vous permet également de compresser des fichiers audio intégrés pour réduire leur taille (mais ceci se fait au détriment de la qualité du son). Pour plus d’informations, voir « Importation de sons » dans Utilisation de Flash. L’architecture audio d’ActionScript 3.0 utilise les classes suivantes dans le package flash.media. Classe
Les classes Sound, SoundChannel, et SoundMixer ne sont pas utilisées pour les données audio provenant d’un microphone ou d’une transmission de passerelle multimédia en continu (Flash Media Server, par exemple).
Chargement de fichiers audio externes Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Chaque occurrence de la classe Sound permet de charger et de déclencher la lecture d’une ressource audio spécifique. Une application ne peut pas réutiliser un objet Sound pour charger plusieurs sons. Si elle souhaite charger une nouvelle ressource audio, elle doit créer un objet Sound. Si vous chargez un fichier audio de petite taille (un son clic à associer à un bouton, par exemple), votre application peut créer un objet Sound qui charge automatiquement le fichier audio, comme indiqué ci-dessous : var req:URLRequest = new URLRequest("click.mp3"); var s:Sound = new Sound(req);
Dans le meilleur des cas, votre application doit surveiller la progression du chargement du son et rechercher les erreurs pendant le chargement. Par exemple, si le son clic est volumineux, il risque de ne pas être totalement chargé lorsque l’utilisateur clique sur le bouton qui déclenche le son. Si vous tentez de lire un son non chargé, une erreur d’exécution risque de se produire. Il est préférable d’attendre la fin du chargement du son avant de permettre aux utilisateurs d’effectuer des actions risquant de lancer la lecture des sons. Un objet Sound envoie plusieurs événements différents pendant le chargement du son. Votre application peut écouter ces événements pour suivre la progression du chargement et vérifier que le son est complètement chargé avant la lecture. Le tableau suivant répertorie les événements pouvant être envoyés par un objet Sound. Evénement
Tout d’abord, l’exemple de code crée un objet Sound sans lui donner de valeur initiale pour le paramètre URLRequest. Ensuite, il écoute l’événement Event.COMPLETE issu de l’objet Sound. La méthode onSoundLoaded() s’exécute alors lorsque toutes les données audio sont chargées. Puis, il appelle la méthode Sound.load() avec une nouvelle valeur URLRequest pour le fichier audio. La méthode onSoundLoaded() s’exécute lorsque le chargement du son est terminé. La propriété target de l’objet Event est une référence à l’objet Sound. L’appel à la méthode play() de l’objet Sound lance ensuite la lecture du son.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les fichiers audio peuvent être très volumineux et leur chargement très long. Flash Player et AIR permettent à votre application de lire des sons avant leur chargement complet. Vous pouvez indiquer à l’utilisateur la quantité de données audio ayant été chargées et la quantité de son déjà lue. La classe Sound envoie deux événements permettant d’afficher facilement la progression du chargement d’un son : ProgressEvent.PROGRESS et Event.COMPLETE. L’exemple suivant indique comment utiliser ces événements pour afficher les informations de progression concernant le son en cours de chargement : import import import import
Le pourcentage des données audio chargées est équivalent à la valeur de la propriété bytesLoaded de l’objet ProgressEvent divisé par la valeur de la propriété bytesTotal. Les mêmes propriétés bytesLoaded et bytesTotal sont disponibles sur l’objet Sound également. L’exemple ci-dessus indique les messages relatifs à la progression du chargement du son, mais vous pouvez facilement utiliser les valeurs bytesLoaded et bytesTotal pour mettre à jour les composants de la barre de progression, tels que ceux intégrés à la structure d’Adobe Flex ou à l’outil de programmation d’Adobe Flash. Cet exemple indique également comment une application peut reconnaître et répondre à une erreur lors du chargement des fichiers audio. Par exemple, si un fichier audio avec le nom de fichier donné est introuvable, un événement Event.IO_ERROR est envoyé par l’objet Sound. Dans le code précédent, la méthode onIOError() s’exécute et affiche un message d’erreur court lorsqu’une erreur se produit.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Utilisez des sons intégrés (au lieu de charger du son depuis un fichier externe) surtout dans le cas de fichiers audio de petite taille servant d’indicateurs dans l’interface utilisateur de votre application (des sons qui sont lus lorsque vous cliquez sur des boutons, par exemple). Lorsque vous incorporez un fichier audio dans votre application, la taille du fichier SWF résultant augmente proportionnellement à la taille du fichier audio. Ceci signifie que lorsque vous incorporez des fichiers volumineux dans votre application, la taille de votre fichier SWF risque de devenir trop importante. La méthode exacte à utiliser pour incorporer un fichier de police dans le fichier SWF de l’application varie selon l’environnement de développement.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’outil de programmation Flash vous permet d’importer des sons dans un grand nombre de formats audio et de les stocker comme symboles dans la bibliothèque. Vous pouvez ensuite les affecter à des images dans le scénario ou aux images d’un état de bouton, les utiliser avec des comportements ou directement dans du code ActionScript. Cette section décrit comment utiliser des sons incorporés dans du code ActionScript avec l’outil de programmation Flash. Pour plus d’informations sur les autres façons d’utiliser des sons incorporés dans Flash, voir « Importation de sons » dans Utilisation de Flash. Pour intégrer un fichier son à l’aide de l’outil de programmation Flash : 1 Sélectionnez Fichier > Importer > Importer dans la bibliothèque, puis sélectionnez un fichier audio et importez-le. 2 Cliquez avec le bouton droit de la souris sur le nom du fichier importé dans le panneau Bibliothèque, et sélectionnez
3 Dans le champ Classe, entrez un nom à utiliser lorsque vous faites référence à ce son incorporé dans ActionScript.
DrumSound.mp3), vous devez le remplacer par DrumSound ; ActionScript n’autorise pas le caractère point dans les noms de classe. Le champ Classe de base devrait encore afficher flash.media.Sound.
4 Cliquez sur OK. Il se peut qu’une boîte de dialogue indiquant qu’une définition pour cette classe est introuvable
à celui d’une classe contenue dans le chemin de classe de votre application, une nouvelle classe qui hérite de la classe flash.media.Sound est générée automatiquement. 5 Pour utiliser le son incorporé, vous référencez le nom de classe pour ce son dans ActionScript. Par exemple, le code
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Il existe plusieurs moyens d’intégrer des ressources son dans une application Flex. Vous pouvez par exemple :
• utiliser la directive @Embed dans MXML pour affecter une ressource intégrée en tant que propriété d’un composant, telle que Button ou SoundEffect ;
Cette section décrit la première option : comment intégrer des sons dans le code ActionScript au sein d’une application Flex à l’aide de la balise de métadonnées [Embed]. Pour intégrer un élément dans le code ActionScript, utilisez la balise de métadonnées [Embed]. Placez le fichier audio dans le dossier source principal ou dans un autre dossier qui se trouve dans le chemin de création de votre projet. Lorsque le compilateur détecte une balise de métadonnées Embed, il crée la classe d’actifs intégrés à votre intention. Vous pouvez accéder à la classe par le biais d’une variable de données de type Class que vous déclarez immédiatement après la balise de métadonnées [Embed]. Le code suivant intègre un son appelé smallSound.mp3 et utilise une variable appelée soundClass pour stocker une référence à la classe de ressources intégrées associée à ce son. Le code crée ensuite une occurrence de la classe de ressources intégrées, l’attribue comme une occurrence de la classe Sound et appelle la méthode play() sur cette occurrence :
Utilisation de fichiers audio de lecture en continu Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lorsqu’un fichier audio ou un fichier vidéo est lu alors que ses données sont encore en cours de chargement, il est lu en continu. Les fichiers audio externes chargés depuis un serveur distant sont souvent lus en continu de façon à ce que l’utilisateur ne doive pas attendre le chargement complet des données audio pour écouter le son. La propriété SoundMixer.bufferTime représente le nombre de millisecondes de données audio que Flash Player ou AIR doit rassembler avant la lecture du son. En d’autres termes, si la propriété bufferTime est définie sur 5000, Flash Player ou AIR charge au moins 5 000 millisecondes de données depuis le fichier audio avant le début de la lecture du son. La valeur SoundMixer.bufferTime par défaut est 1000. Votre application peut ignorer la valeur SoundMixer.bufferTime globale pour un son individuel en spécifiant explicitement une nouvelle valeur bufferTime lors du chargement du son. Pour ignorer la durée du tampon par défaut, créez d’abord une occurrence de la classe SoundLoaderContext, définissez sa propriété bufferTime, puis transmettez-la comme paramètre à la méthode Sound.load(), comme indiqué ci-dessous : import flash.media.Sound; import flash.media.SoundLoaderContext; import flash.net.URLRequest; var s:Sound = new Sound(); var req:URLRequest = new URLRequest("bigSound.mp3"); var context:SoundLoaderContext = new SoundLoaderContext(8000, true); s.load(req, context); s.play();
Pendant la lecture, Flash Player ou AIR tente de conserver le tampon audio à la même taille ou à une taille supérieure. Si le téléchargement des données audio est plus rapide que la vitesse de la lecture, cette dernière continue sans interruption. Néanmoins, si la vitesse de chargement des données est ralentie en raison des limites du réseau, la tête de lecture peut atteindre la fin du tampon audio. Dans ce cas, la lecture est suspendue mais elle reprend automatiquement lorsque d’autres données audio sont chargées. Pour savoir si la lecture est suspendue car Flash Player ou AIR attend le chargement des données, utilisez la propriété Sound.isBuffering.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures Remarque : Flash Player 10 et Adobe AIR 1.5 donnent désormais la possibilité de générer des données audio de façon dynamique. Plutôt que de charger ou de diffuser en continu un son existant, vous pouvez générer des données audio de façon dynamique. Vous pouvez générer des données audio lorsque vous affectez un écouteur associé à l’événement sampleData d’un objet Sound (l’événement sampleData est défini dans la classe SampleDataEvent du package flash.events). Dans cet environnement, l’objet Sound ne charge pas de données audio à partir d’un fichier. Il agit en fait en tant que socket pour les données audio qui lui sont diffusées en continu par l’intermédiaire de la fonction que vous affectez à cet événement. Lorsque vous ajoutez un écouteur d’événement sampleData à un objet Sound, celui-ci demande périodiquement des données à ajouter au tampon audio. Ce tampon contient des données destinées à être lues par l’objet. Une fois appelé, la méthode play() de l’objet Sound distribue l’événement sampleData lorsqu’il demande de nouvelles données audio. Ceci n’est vrai que si l’objet Sound n’a pas chargé de données mp3 à partir d’un fichier. L’objet SampleDataEvent comprend une propriété data. Dans votre écouteur d’événement, vous écrivez des objets ByteArray dans cet objet data. Les tableaux d’octets que vous écrivez dans cet objet s’ajoutent aux données figurant dans le tampon que lit l’objet Sound. Le tableau d’octets que contient le tampon est un flux de valeurs en virgule flottante comprises en -1 et 1. Chaque valeur représente l’amplitude d’un canal unique (gauche ou droit) d’un échantillon audio. Le son est échantillonné à 44 100 échantillons par seconde. Chaque échantillon contient un canal gauche et un canal droit, entrelacés sous forme de données en virgule flottante dans le tableau d’octets. Dans votre fonction gestionnaire, vous utilisez la méthode ByteArray.writeFloat() pour écrire dans la propriété data de l’événement sampleData. Par exemple, le code suivant génère une onde sinusoïdale : var mySound:Sound = new Sound(); mySound.addEventListener(SampleDataEvent.SAMPLE_DATA, sineWaveGenerator); mySound.play(); function sineWaveGenerator(event:SampleDataEvent):void { for (var i:int = 0; i < 8192; i++) { var n:Number = Math.sin((i + event.position) / Math.PI / 4); event.data.writeFloat(n); event.data.writeFloat(n); } Lorsque vous appelez Sound.play(), l’application commence à appeler votre gestionnaire d’événement pour demander des données audio d’échantillonnage. Elle continue à envoyer des événements pendant la lecture du son jusqu’à ce que vous cessiez de fournir des données ou que vous appeliez la méthode SoundChannel.stop(). La période d’attente de l’événement varie selon les plates-formes et peut encore changer dans les futures versions de Flash Player et AIR. Plutôt que de vous appuyer sur une période d’attente spécifique, calculez-la. Pour calculer la période d’attente, utilisez la formule suivante : (SampleDataEvent.position / 44.1) - SoundChannelObject.position
Si vous fournissez moins de 2 048 échantillons (par appel de l’écouteur d’événement sampleData), l’application s’arrête à l’issue de la lecture des échantillons restants. L’objet SoundChannel distribue alors un événement SoundComplete.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures La méthode SoundExtract vous permet d’extraire des données d’un objet Sound. Vous pouvez utiliser (et modifier) ces données pour accéder en écriture au flux continu dynamique d’un autre objet Sound à des fins de lecture. Ainsi, le code suivant utilise les octets d’un fichier MP3 chargé et les transmet par le biais d’une fonction de filtre, upOctave() :
Lecture de sons Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lire un son chargé peut être aussi simple qu’appeler la méthode Sound.play() pour un objet Sound, comme suit : var snd:Sound = new Sound(new URLRequest("smallSound.mp3")); snd.play();
• Interrompre un son et reprendre la lecture ultérieurement à partir de la même position
• Savoir exactement lorsque la lecture d’un son est terminée • Suivre la progression de la lecture d’un son • Modifier le volume ou la balance pendant la lecture d’un son Pour effectuer ces opérations pendant la lecture, utilisez les classes SoundChannel, SoundMixer et SoundTransform. La classe SoundChannel contrôle la lecture d’un seul son. La propriété SoundChannel.position peut être considérée comme une tête de lecture qui indique le point actuel dans les données audio en cours de lecture. Lorsqu’une application appelle la méthode Sound.play(), une occurrence de la classe SoundChannel est créée pour contrôler la lecture. Votre application peut lire un son à partir d’une position de début spécifique en la transmettant, en termes de millisecondes, comme paramètre startTime de la méthode Sound.play(). Elle peut également spécifier un nombre fixe de répétitions du son en succession rapide en transmettant une valeur numérique dans le paramètre loops de la méthode Sound.play(). Lorsque la méthode Sound.play() est appelée avec un paramètre startTime et un paramètre loops, le son est lu de façon répétée à partir du même point de début chaque fois, comme indiqué dans le code suivant : var snd:Sound = new Sound(new URLRequest("repeatingSound.mp3")); snd.play(1000, 3);
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Si votre application lit des sons longs (chansons ou podcasts, par exemple), vous pouvez permettre aux utilisateurs d’interrompre et de reprendre leur lecture. Il est impossible d’interrompre littéralement un son pendant la lecture dans ActionScript ; vous pouvez uniquement l’arrêter. Néanmoins, un son peut être lu à partir de n’importe quel point. Vous pouvez enregistrer la position du son au moment de l’arrêt puis le relire ultérieurement à partir de cette position. Par exemple, supposons que votre code charge et lit un fichier audio de la façon suivante : var snd:Sound = new Sound(new URLRequest("bigSound.mp3")); var channel:SoundChannel = snd.play();
Surveillance de la lecture Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Votre application a peut-être besoin de savoir lorsque la lecture d’un son s’arrête afin de lancer la lecture d’un autre son ou d’effacer des ressources utilisées pendant la lecture précédente. La classe SoundChannel envoie un événement Event.SOUND_COMPLETE à la fin de la lecture du son. Votre application peut écouter cet événement et effectuer l’action appropriée, comme indiqué ci-dessous : import flash.events.Event; import flash.media.Sound; import flash.net.URLRequest; var snd:Sound = new Sound(); var req:URLRequest = new URLRequest("smallSound.mp3"); snd.load(req); var channel:SoundChannel = snd.play(); channel.addEventListener(Event.SOUND_COMPLETE, onPlaybackComplete); public function onPlaybackComplete(event:Event) { trace("The sound has finished playing."); } Néanmoins, ce code signale uniquement des pourcentages de lecture précis si les données audio ont été totalement chargées avant le début de la lecture. La propriété Sound.length indique la taille des données audio actuellement chargées, et non pas la taille éventuelle du fichier audio entier. Pour suivre la progression de la lecture d’un son diffusé en continu qui est toujours en cours de chargement, votre application doit estimer la taille éventuelle du fichier audio entier et utiliser cette valeur dans ses calculs. Vous pouvez estimer la longueur éventuelle des données audio à l’aide des propriétés bytesLoaded et bytesTotal de l’objet Sound, comme suit : var estimatedLength:int = Math.ceil(snd.length / (snd.bytesLoaded / snd.bytesTotal)); var playbackPercent:uint = 100 * (channel.position / estimatedLength);
Event.SOUND_COMPLETE qui a lieu à la fin de la lecture. Chaque fois que l’application atteint une nouvelle image dans son animation, la méthode onEnterFrame() est appelée. La méthode onEnterFrame() estime la longueur totale du fichier audio en fonction de la quantité de données déjà chargées puis calcule et affiche le pourcentage de lecture actuel. Une fois que tout le son a été lu, la méthode onPlaybackComplete() s’exécute, supprimant l’écouteur d’événement pour l’événement Event.ENTER_FRAME de façon à ce qu’il ne tente pas d’afficher les mises à jour de progression après la lecture. L’événement Event.ENTER_FRAME peut être envoyé plusieurs fois par seconde. Dans certains cas, vous pouvez ne pas afficher la progression de la lecture aussi fréquemment. Votre application peut alors définir son propre mécanisme de synchronisation à l’aide de la classe flash.util.Timer ; voir « Utilisation des dates et des heures » à la page 1.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Il y a quelque chose d’étrange dans le processus de lecture des sons diffusés en continu, c’est-à-dire ceux qui sont lus pendant leur chargement. Lorsque votre application appelle la méthode SoundChannel.stop() sur une occurrence de SoundChannel qui lit un son diffusé en continu, la lecture du son s’arrête pendant une image puis elle relance au début du son sur l’image suivante. Ceci a lieu car le chargement du son est toujours en cours. Pour arrêter à la fois le chargement et la lecture d’un son diffusé en continu, appelez la méthode Sound.close().
Sécurité lors du chargement et de la lecture des sons Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’accès aux données audio par votre application peut être limité selon la fonction de sécurité de Flash Player ou AIR. Chaque son est soumis aux restrictions de deux sandbox de sécurité différents, le sandbox pour le contexte lui-même (le sandbox de contexte), et le sandbox pour l’application ou l’objet qui charge et lit le son (le sandbox propriétaire). Pour le contenu de l’application AIR dans le sandbox de sécurité de l’application, tous les sons, y compris ceux chargés à partir d’autres domaines, sont accessibles au contenu dans le sandbox de sécurité de l’application. Toutefois, le contenu dans d’autres sandbox de sécurité observe les même règles que le contenu qui s’exécute dans Flash Player. Pour plus d’informations sur le modèle de sécurité de Flash Player en général et la définition des sandbox, voir « Sécurité » à la page 1085. Le sandbox de contexte contrôle si des données audio détaillées peuvent être extraites du son à l’aide de la propriété id3 ou de la méthode SoundMixer.computeSpectrum(). Il ne limite pas le chargement ou la lecture du fichier audio lui-même. Le domaine d’origine du fichier audio définit les limites de sécurité du sandbox de contexte. Généralement, si un fichier audio se trouve dans le même domaine ou dossier que le fichier SWF de l’application ou de l’objet qui le charge, ce dernier dispose d’un accès total à ce fichier audio. Si le son provient d’un domaine différent par rapport à l’application, il peut être intégré dans le sandbox de contexte à l’aide d’un fichier de régulation. Votre application peut transmettre un objet SoundLoaderContext avec une propriété checkPolicyFile comme paramètre à la méthode Sound.load(). Lorsque vous définissez la propriété checkPolicyFile sur true, vous indiquez à Flash Player ou à AIR de rechercher un fichier de régulation sur le serveur à partir duquel le son est chargé. Si un fichier de régulation existe et qu’il autorise l’accès au domaine du fichier SWF de chargement, ce dernier peut charger le fichier audio, accéder à la propriété id3 de l’objet Sound et appeler la méthode SoundMixer.computeSpectrum() pour les sons chargés. Le sandbox propriétaire contrôle la lecture locale des sons. L’application ou l’objet qui lance la lecture d’un son définit le sandbox propriétaire. La méthode SoundMixer.stopAll() interrompt les sons dans tous les objets SoundChannel en cours de lecture, tant qu’ils répondent aux critères suivants :
• Les sons sont issus d’une source possédant un fichier de régulation qui autorise l’accès au domaine de l’application ou de l’objet qui appelle la méthode SoundMixer.stopAll(). Cependant, dans une application AIR, le contenu du sandbox de sécurité de l’application (contenu installé avec l’application AIR) n’est pas restreint par ces limites de sécurité. Pour savoir si la méthode SoundMixer.stopAll() interrompra tous les sons lus, votre application peut appeler la méthode SoundMixer.areSoundsInaccessible(). Si cette méthode renvoie une valeur true, certains des sons lus ne sont pas sous le contrôle du sandbox propriétaire actuel et ne seront pas arrêtés par la méthode SoundMixer.stopAll(). La méthode SoundMixer.stopAll() empêche également la tête de lecture de continuer pour tous les sons chargés à partir de fichiers externes. Néanmoins, les sons qui sont incorporés dans des fichiers FLA et associés à des images dans le scénario à l’aide de l’outil de programmation Flash risquent d’être relus si l’animation s’est déplacée sur une nouvelle image.
Contrôle du volume du son et de la balance Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Un objet SoundChannel individuel contrôle les canaux stéréo gauche et droit pour un son. Si un son mp3 est un son mono, les canaux stéréo gauche et droit de l’objet SoundChannel contiennent des courbes audio identiques. Vous pouvez connaître l’amplitude de chaque canal stéréo du son lu à l’aide des propriétés leftPeak et rightPeak de l’objet SoundChannel. Ces propriétés indiquent l’amplitude de crête de la courbe audio du son. Elles ne représentent pas le volume de lecture réel. Le volume de lecture réel est une fonction de l’amplitude de l’onde acoustique et des valeurs de volume définies dans l’objet SoundChannel et la classe SoundMixer. Vous pouvez utiliser la propriété pan d’un objet SoundChannel pour indiquer un niveau de volume différent pour chacun des canaux gauche et droit pendant la lecture. La propriété pan peut avoir une valeur comprise entre -1 et 1, où -1 signifie que le canal gauche lit à volume maximal alors que le canal droit est muet, et 1 signifie que le canal droit lit à volume maximal alors que le canal gauche est muet. Les valeurs numériques comprises entre -1 et 1 définissent des valeurs proportionnelles pour les valeurs des canaux gauche et droit, et une valeur de 0 signifie que les deux canaux lisent à un niveau de volume moyen, équilibré. L’exemple de code suivant crée un objet SoundTransform avec une valeur de volume de 0,6 et une valeur de balance horizontale de -1 (volume de canal gauche maximal et aucun volume de canal droit). Il transmet l’objet SoundTransform comme paramètre à la méthode play(), qui l’applique au nouvel objet SoundTransform créé pour contrôler la lecture. var snd:Sound = new Sound(new URLRequest("bigSound.mp3")); var trans:SoundTransform = new SoundTransform(0.6, -1); var channel:SoundChannel = snd.play(0, 1, trans);
SoundChannel. Vous pouvez également définir des valeurs de balance et de volume global pour tous les sons à la fois à l’aide de la propriété soundTransform de la classe SoundMixer, comme l’indique l’exemple suivant : SoundMixer.soundTransform = new SoundTransform(1, -1);
L’exemple suivant modifie la balance horizontale du son du canal gauche au canal droit et de nouveau lors de la lecture du son.
Pour exécuter cet exemple, remplacez le nom de fichier bigSound.mp3 par le nom d’un fichier mp3 local. Exécutez ensuite l’exemple. Le volume du canal gauche devrait augmenter quand celui du canal droit diminue, et vice-versa. Dans cet exemple, le même effet peut être obtenu en définissant la propriété soundTransform de la classe SoundMixer. Néanmoins, la balance de tous les sons en cours de lecture est affectée (pas seulement le son lu par cet objet SoundChannel).
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les fichiers audio qui utilisent le format mp3 peuvent contenir des données supplémentaires relatives au son sous la forme de balises ID3.
Tous les fichiers mp3 ne contiennent pas de métadonnées ID3. Lorsqu’un objet Sound charge un fichier audio mp3, il envoie un événement Event.ID3 si le fichier audio contient des métadonnées ID3. Pour éviter des erreurs d’exécution, votre application doit attendre de recevoir l’événement Event.ID3 avant d’accéder à la propriété Sound.id3 pour un son chargé. Le code suivant indique comment savoir si les métadonnées ID3 pour un fichier audio ont été chargées : import flash.events.Event; import flash.media.ID3Info; import flash.media.Sound; var s:Sound = new Sound(); s.addEventListener(Event.ID3, onID3InfoReceived); s.load("mySound.mp3"); function onID3InfoReceived(event:Event) { var id3:ID3Info = event.target.id3; trace("Received ID3 Info:"); for (var propName:String in id3) { trace(propName + " = " + id3[propName]); } Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La méthode SoundMixer.computeSpectrum() permet à une application de lire les données audio brutes pour la courbe audio en cours de lecture. Si plusieurs objets SoundChannel sont en cours de lecture, la méthode SoundMixer.computeSpectrum() indique les données audio combinées de chaque objet SoundChannel mixé. Les données audio sont renvoyées sous la forme d’un objet ByteArray contenant 512 octets de données (chacun d’eux contenant une valeur en virgule flottante comprise entre -1 et 1). Ces valeurs représentent l’amplitude des points dans la courbe audio en cours de lecture. Les valeurs sont fournies en deux groupes de 256 : le premier groupe pour le canal stéréo gauche et le second pour le canal stéréo droit. La méthode SoundMixer.computeSpectrum() renvoie des données de spectre de fréquences plutôt que des données de courbe audio si le paramètre FFTMode est défini sur true. Le spectre de fréquences indique l’amplitude par fréquence du son, de la plus basse à la plus élevée. Une FFT (Fast Fourier Transform - transformation de Fourier rapide) est utilisée pour convertir les données de courbe audio en données de spectre de fréquences. Les valeurs de spectre de fréquences résultantes sont comprises entre 0 et 1,414 environ (la racine carrée de 2).
Le diagramme suivant compare les données renvoyées de la méthode computeSpectrum() lorsque le paramètre FFTMode est défini sur true et lorsqu’il est défini sur false. Le son dont les données ont été utilisées pour ce diagramme contient un son de basse de grande intensité dans le canal gauche et un son de tambour dans le canal droit.
A. fftMode=true B. fftMode=false
256 octets par canal stéréo lorsqu’une valeur stretchFactor supérieure est utilisée. La méthode SoundMixer.computeSpectrum() comporte des limites :
à la page 1111. Cependant, dans une application AIR, le contenu du sandbox de sécurité de l’application (contenu installé avec l’application AIR) n’est pas restreint par ces limites de sécurité.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’exemple suivant utilise la méthode SoundMixer.computeSpectrum() pour afficher un diagramme de la courbe audio animée avec chaque image : import import import import import import
Capture de l’entrée de son Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe Microphone permet à votre application de se connecter à un microphone ou à un autre périphérique d’entrée de son sur le système de l’utilisateur et de diffuser l’audio sur les haut-parleurs de ce système ou d’envoyer les données audio à un serveur distant (Flash Media Server, par exemple). Vous pouvez accéder aux données audio brutes à partir du microphone, puis les enregistrer ou les traiter. Vous pouvez également envoyer directement l’audio aux hautparleurs du système ou envoyer des données audio compressées à un serveur distant. Pour envoyer des données à un serveur distant, vous pouvez utiliser le codec Speex ou Nellymoser (le codec Speex est pris en charge depuis Flash Player version 10 et Adobe AIR version 1.5).
Michael Chaize : AIR, Android, and the Microphone (disponible en anglais uniquement) La classe Microphone ne possède pas de méthode constructeur. A la place, vous utilisez la méthode statique Microphone.getMicrophone() pour obtenir une nouvelle occurrence de Microphone, comme indiqué ci-dessous : var mic:Microphone = Microphone.getMicrophone();
Un système peut avoir plusieurs périphériques d’entrée de son qui lui sont associés. Votre application peut utiliser la propriété Microphone.names pour obtenir un tableau des noms de tous les périphériques d’entrée de son disponibles. Elle peut ensuite appeler la méthode Microphone.getMicrophone() avec un paramètre index qui correspond à la valeur d’index du nom d’un périphérique dans le tableau. Il se peut qu’un système n’ait aucun microphone ni périphérique d’entrée de son qui lui soit associé. Vous pouvez utiliser la propriété Microphone.names ou la méthode Microphone.getMicrophone() pour vérifier si l’utilisateur a installé un périphérique d’entrée de son. Si ce n’est pas le cas, la longueur du tableau names est zéro, et la méthode getMicrophone() renvoie une valeur null. Lorsque votre application appelle la méthode Microphone.getMicrophone(), Flash Player affiche la boîte de dialogue des paramètres de Flash Player, qui invite l’utilisateur à autoriser ou à refuser l’accès Flash Player à la caméra et au microphone sur le système. Une fois que l’utilisateur a fait son choix dans cette boîte de dialogue, un StatusEvent est envoyé. La propriété code de cette occurrence de StatusEvent indique si l’accès au microphone a été autorisé ou refusé, comme indiqué dans cet exemple :
Un contenu qui s’exécute dans le sandbox de l’application AIR ne nécessite pas l’autorisation de l’utilisateur pour accéder au microphone. Par conséquent, les événements d’état associés à l’activation et à la désactivation du microphone ne sont jamais distribués. Etant donné qu’un contenu qui s’exécute dans AIR en dehors du sandbox de l’application ne nécessite pas l’autorisation de l’utilisateur, il est possible de distribuer ces événements d’état.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’entrée audio issue d’un microphone peut être acheminée vers les haut-parleurs du système local en appelant la méthode Microphone.setLoopback() avec une valeur de paramètre true. Lorsque le son provenant d’un microphone local est acheminé vers des haut-parleurs locaux, vous risquez de créez une boucle de réaction acoustique pouvant entraîner des grincements d’une grande intensité et endommager ainsi votre matériel. Vous pouvez appeler la méthode Microphone.setUseEchoSuppression() avec une valeur de paramètre true pour réduire (sans éliminer complètement) le risque de réaction acoustique. Adobe vous conseille de toujours appeler Microphone.setUseEchoSuppression(true) avant d’appeler Microphone.setLoopback(true), à moins que vous soyez sûr que l’utilisateur lit le son à l’aide d’un casque ou d’un dispositif autre que les haut-parleurs. Le code suivant indique comment acheminer l’audio d’un microphone local vers les haut-parleurs du système local : var mic:Microphone = Microphone.getMicrophone(); mic.setUseEchoSuppression(true); mic.setLoopBack(true);
Modification de l’audio du microphone Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Votre application peut modifier les données audio provenant d’un microphone de deux façons différentes. Premièrement, elle peut modifier le gain du son entré, qui multiplie les valeurs d’entrée par une quantité spécifiée pour créer un son plus ou moins intense. La propriété Microphone.gain accepte des valeurs numériques comprises entre 0 et 100 inclus. Une valeur de 50 a un rôle de multiplicateur de un et spécifie un volume normal. Une valeur de zéro agit comme un multiplicateur de zéro et interrompt l’audio d’entrée. Les valeurs supérieures à 50 indiquent un volume supérieur à la normale. Votre application peut également modifier la fréquence d’échantillonnage de l’audio d’entrée. Des fréquences d’échantillonnage supérieures augmentent la qualité du son, mais créent également des flux de données plus denses qui utilisent davantage de ressources pour la transmission et le stockage. La propriété Microphone.rate représente la fréquence d’échantillonnage audio mesurée en kilohertz (kHz). La fréquence d’échantillonnage par défaut est de 8 kHz. Vous pouvez définir la propriété Microphone.rate sur une valeur supérieure à 8 kHz si votre microphone prend en charge la fréquence supérieure. Par exemple, si vous définissez la propriété Microphone.rate sur la valeur 11, la fréquence d’échantillonnage est réglée sur 11 kHz ; si vous la définissez sur 22, la fréquence d’échantillonnage est réglée sur 22 kHz, et ainsi de suite. Les fréquences d’échantillonnage disponibles varient en fonction du codec sélectionné. Lorsque vous utilisez le codec Nellymoser, vous pouvez spécifier les fréquences d’échantillonnage 5, 8, 11, 16, 22 et 44 kHz. Lorsque vous utilisez le codec Speex (disponible à partir de Flash Player 10 et Adobe AIR 1.5), vous ne pouvez utiliser que 16 kHz.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour économiser les ressources de traitement et de bande passante, Flash Player tente de détecter lorsque aucun son n’est transmis par un microphone. Lorsque le niveau d’activité du microphone se situe sous le seuil de niveau de silence pendant longtemps, Flash Player arrête la transmission de l’entrée audio et envoie un simple événement ActivityEvent à la place. Si vous utilisez le codec Speex (disponible dans Flash Player 10 et versions ultérieures, ainsi que dans Adobe AIR 1.5 et versions ultérieures), définissez le niveau de silence sur 0 afin de vous assurer que l’application transmet les données audio en continu. La fonction de détection d’activité vocale de Speex réduit automatiquement la bande passante. Remarque : un objet Microphone ne distribue des événements Activity que si l’application contrôle actuellement le microphone. Par conséquent, si vous n’appelez pas setLoopBack( true ), que vous n’associez pas d’écouteur aux événements de données d’exemple ou que vous ne connectez pas le microphone à un objet NetStream, aucun événement d’activité n’est distribué. Trois propriétés de la classe Microphone surveillent et contrôlent la détection d’activité :
événement ActivityEvent.ACTIVITY. La propriété silenceLevel utilise également une échelle de 0 à 100, et la valeur par défaut est 10.
Les propriétés Microphone.silenceLevel et Microphone.silenceTimeout sont en lecture seule, mais vous pouvez modifier leurs valeurs à l’aide de la méthode Microphone.setSilenceLevel(). Dans certains cas, l’activation du microphone alors qu’une nouvelle activité est détectée peut entraîner un court délai. Vous pouvez laisser le microphone actif en permanence pour supprimer ces délais d’activation. Votre application peut appeler la méthode Microphone.setSilenceLevel() avec le paramètre silenceLevel défini sur zéro pour indiquer à Flash Player de laisser le microphone actif et de continuer à rassembler des données audio, même lorsque aucun son n’est détecté. Inversement, lorsque vous définissez le paramètre silenceLevel sur 100, le microphone n’est pas activé. L’exemple suivant affiche les informations relatives au microphone et aux événements activity et status envoyés par un objet Microphone : import flash.events.ActivityEvent; import flash.events.StatusEvent; import flash.media.Microphone; var deviceArray:Array = Microphone.names; trace("Available sound input devices:"); for (var i:int = 0; i < deviceArray.length; i++) { trace(" " + deviceArray[i]); } var mic:Microphone = Microphone.getMicrophone(); mic.gain = 60; mic.rate = 11; mic.setUseEchoSuppression(true); mic.setLoopBack(true); mic.setSilenceLevel(5, 1000); mic.addEventListener(ActivityEvent.ACTIVITY, this.onMicActivity); mic.addEventListener(StatusEvent.STATUS, this.onMicStatus); var micDetails:String = "Sound input device name: " + mic.name + '\n'; micDetails += "Gain: " + mic.gain + '\n'; micDetails += "Rate: " + mic.rate + " kHz" + '\n'; micDetails += "Muted: " + mic.muted + '\n'; micDetails += "Silence level: " + mic.silenceLevel + '\n'; micDetails += "Silence timeout: " + mic.silenceTimeout + '\n'; micDetails += "Echo suppression: " + mic.useEchoSuppression + '\n'; trace(micDetails); function onMicActivity(event:ActivityEvent):void { trace("activating=" + event.activating + ", activityLevel=" + mic.activityLevel); Envoi d’audio vers et depuis une passerelle multimédia Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures D’autres fonctionnalités audio sont disponibles lorsque vous utilisez ActionScript avec une passerelle multimédia de diffusion en continu telle que Flash Media Server. Votre application peut notamment associer un objet Microphone à un objet NetStream et transmettre directement des données du microphone de l’utilisateur au serveur. Les données audio peuvent également être diffusées en continu du serveur vers une application et lues dans le cadre d’un MovieClip ou au moyen d’un objet Video. Le codec Speex est pris en charge depuis Flash Player version 10 et Adobe AIR version 1.5. Pour définir le codec utilisé pour les données audio compressées envoyées au serveur multimédia, définissez la propriété codec de l’objet Microphone. Cette propriété gère deux valeurs, qui sont énumérées dans la classe SoundCodec. La définition de la propriété codec sur SoundCodec.SPEEX sélectionne le codec Speex pour la compression audio. La définition de la propriété codec sur SoundCodec.NELLYMOSER (valeur par défaut) sélectionne le codec Nellymoser pour la compression audio. Pour plus d’informations, voir la documentation de Flash Media Server disponible en ligne à l’adresse suivante : www.adobe.com/go/learn_fms_docs_fr.
Flash Player 10.1 et les versions ultérieures, Adobe AIR 2 et les versions ultérieures Dans Flash Player 10.1 et AIR 2 ou ultérieur, vous pouvez capturer les données issues d’un microphone sous forme de tableau d’octets composé de valeurs à virgule flottante. Chaque valeur représente un échantillon de données audio monophoniques. Pour obtenir les données issues d’un microphone, définissez un écouteur associé à l’événement sampleData de l’objet Microphone. L’objet Microphone distribue les événements sampleData à fréquence régulière au fur et à mesure que le tampon du microphone se remplit d’échantillons audio. La propriété data de l’objet SampleDataEvent correspond à un tableau d’octets d’échantillons audio. Les échantillons sont représentés par des valeurs à virgule flottante, chacune d’elles correspondant à un échantillon audio monophonique. Le code suivant capture les données audio issues d’un microphone dans un objet ByteArray appelé soundBytes : var mic:Microphone = Microphone.getMicrophone(); mic.setSilenceLevel(0, DELAY_LENGTH); mic.addEventListener(SampleDataEvent.SAMPLE_DATA, micSampleDataHandler); function micSampleDataHandler(event:SampleDataEvent):void { while(event.data.bytesAvailable) { var sample:Number = event.data.readFloat(); soundBytes.writeFloat(sample); } } Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Un podcast est un fichier audio distribué sur Internet, sur demande ou sur abonnement. Les podcasts sont généralement publiés dans un annuaire. Etant donné que les épisodes de podcast peuvent durer d’une minute à plusieurs heures, ils sont généralement diffusés en continu pendant la lecture. Les épisodes de podcast, également appelés éléments, sont généralement fournis au format de fichier mp3. Les podcasts vidéo sont également courants, mais cet exemple d’application lit uniquement des podcasts audio utilisant des fichiers mp3. Cet exemple n’est pas une application agrégatrice de podcasts comprenant toutes les fonctionnalités. Par exemple, elle ne gère pas les abonnements à des podcasts spécifiques et ne mémorise pas les podcasts qu’un utilisateur a écoutés lors de l’exécution suivante de l’application. Il peut servir de point de départ pour un agrégateur de podcasts comprenant toutes les fonctionnalités. L’exemple Podcast Player illustre les techniques de programmation ActionScript suivantes :
• Création d’une classe SoundFacade pour simplifier le chargement et la lecture des fichiers audio • Affichage de la progression de la lecture du son • Interruption et reprise de la lecture du son Pour obtenir les fichiers d’application de cet exemple, voir www.adobe.com/go/learn_programmingAS3samples_flash_fr. Les fichiers d’application Podcast Player se trouvent dans le dossier Samples/PodcastPlayer. L’application se compose des fichiers suivants : Fichier
/RSSItem.as com/example/program La classe ActionScript principale pour l’application. Elle encapsule les méthodes et les événements des classes mingas3/podcastplayer Sound et SoundChannel et ajoute une prise en charge pour l’interruption et la reprise de la lecture. /SoundFacade.as com/example/program Une classe ActionScript qui récupère des données d’une URL distante. mingas3/podcastplayer /URLService.as playerconfig.xml
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’application Podcast Player commence par lire les informations concernant des chaînes de podcasts et leurs épisodes : 1. L’application commence par lire un fichier de configuration XML qui contient une liste des chaînes de podcast et affiche la liste des chaînes pour l’utilisateur. 2. Lorsque l’utilisateur sélectionne l’une des chaînes de podcast, il lit le flux RSS pour la chaîne et affiche une liste des épisodes de chaîne. Cet exemple utilise la classe d’utilitaire URLLoader pour récupérer des données de texte depuis un emplacement distant ou un fichier local. L’application Podcast Player crée d’abord un objet URLLoader pour obtenir une liste des fils de syndication au format XML du fichier playerconfig.xml. Ensuite, lorsque l’utilisateur sélectionne un fil de syndication spécifique dans la liste, un nouvel objet URLLoader est créé pour lire les données RSS de l’URL de ce fil.
SoundFacade Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’architecture audio ActionScript 3.0 est puissante mais complexe. Les applications nécessitant des fonctions de lecture et de chargement de son de base uniquement peuvent utiliser une classe masquant une partie de la complexité en fournissant un ensemble d’appels et d’événements plus simple. Dans l’univers des modèles de conception de logiciel, une telle classe est appelée façade. La classe SoundFacade présente une seule interface permettant d’effectuer les tâches suivantes :
SoundMixer Dernière mise à jour le 27/4/2013
• Interruption et reprise de la lecture du son à l’aide des objets Sound et SoundChannel La classe SoundFacade essaie d’offrir le meilleur de la fonctionnalité des classes de son ActionScript avec moins de complexité. Le code suivant indique la déclaration de classe, les propriétés de classe et la méthode constructeur SoundFacade() : public class SoundFacade extends EventDispatcher { public var s:Sound; public var sc:SoundChannel; public var url:String; public var bufferTime:int = 1000; public public public public public public
La classe SoundFacade étend la classe EventDispatcher pour qu’elle puisse envoyer ses propres événements. Le code de classe déclare d’abord les propriétés pour un objet Sound et un objet SoundChannel. La classe stocke également la valeur de l’URL du fichier audio et une propriété bufferTime à utiliser lors de la lecture du son en continu. De plus, elle accepte des valeurs de paramètre booléennes qui affectent le comportement de lecture et de chargement :
• Le paramètre autoPlay indique que la lecture du son doit commencer dès qu’une quantité suffisante de données audio a été chargée. S’il s’agit d’un son diffusé en continu, la lecture commence dès qu’une quantité suffisante de données (comme spécifié par la propriété bufferTime) est chargée.
Le paramètre bufferTime prend la valeur -1 par défaut. Si la méthode constructeur détecte une valeur négative dans le paramètre bufferTime, elle définit la propriété bufferTime sur la valeur de SoundMixer.bufferTime. Ceci permet à l’application de prendre la valeur SoundMixer.bufferTime globale, par défaut, comme souhaité. Si le paramètre autoLoad est défini sur true, la méthode constructeur appelle immédiatement la méthode load() suivante pour commencer le chargement du fichier audio: public function load():void { if (this.isPlaying) { this.stop(); this.s.close(); } this.isLoaded = false; this.s = new Sound(); this.s.addEventListener(ProgressEvent.PROGRESS, onLoadProgress); this.s.addEventListener(Event.OPEN, onLoadOpen); this.s.addEventListener(Event.COMPLETE, onLoadComplete); this.s.addEventListener(Event.ID3, onID3); this.s.addEventListener(IOErrorEvent.IO_ERROR, onIOError); this.s.addEventListener(SecurityErrorEvent.SECURITY_ERROR, onIOError); var req:URLRequest = new URLRequest(this.url); var context:SoundLoaderContext = new SoundLoaderContext(this.bufferTime, true); this.s.load(req, context); Les trois méthodes d’écouteur d’événement suivantes indiquent comment l’objet SoundFacade suit la progression du chargement et décide quand lancer la lecture du son :
La méthode onLoadProgress() s’exécute régulièrement pendant le chargement. Elle envoie simplement une copie de son objet ProgressEvent pour le code qui utilise cet objet SoundFacade. Une fois que les données audio ont été complètement chargées, la méthode onLoadComplete() s’exécute en appelant la méthode play() pour des sons non diffusés en continu, si nécessaire. La méthode play() est décrite ci-dessous.
Affichage de la progression de la lecture Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La création d’un objet Timer pour surveiller la lecture est une opération complexe que vous devez coder une seule fois. Le fait d’encapsuler cette logique Timer dans une classe réutilisable telle que la classe SoundFacade permet aux applications d’écouter les mêmes types d’événements de progression lorsqu’un son est chargé et lorsqu’il est lu. L’objet Timer créé par la méthode SoundFacade.play() envoie une occurrence de TimerEvent toutes les secondes. La méthode onPlayTimer() s’exécute chaque fois qu’un nouveau TimerEvent arrive : public function onPlayTimer(event:TimerEvent):void { var estimatedLength:int = Math.ceil(this.s.length / (this.s.bytesLoaded / this.s.bytesTotal)); var progEvent:ProgressEvent = new ProgressEvent(PLAY_PROGRESS, false, false, this.sc.position, estimatedLength); this.dispatchEvent(progEvent); SoundChannel et la propriété bytesTotal définie sur la longueur estimée des données audio.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La méthode SoundFacade.play() décrite précédemment accepte un paramètre pos correspondant à une position de début dans les données audio. Si la valeur pos est zéro, la lecture du son commence au début. La méthode SoundFacade.stop() accepte également un paramètre pos, comme indiqué ici :
SoundFacade.stop() et SoundFacade.play() respectivement, transmettant chaque fois une valeur de paramètre pos. public function pause():void { stop(this.sc.position); } public function resume():void { play(this.pausePosition); Cet exemple présente un Podcast Player dépouillé qui présente l’utilisation de la classe SoundFacade réutilisable. Vous pouvez ajouter d’autres fonctions pour améliorer l’utilité de cette application, notamment :
• mémoriser la position de la tête de lecture lorsque l’utilisateur arrête ou quitte un épisode de façon à ce qu’il puisse être redémarré à partir de ce point la prochaine fois que l’utilisateur exécute l’application ;
La vidéo avec Flash est l’une des technologies dominantes d’Internet. Toutefois, l’interface traditionnelle de la vidéo, dans un écran rectangulaire avec une barre de progression surmontant des boutons de contrôle, n’est que l’un des usages possibles de la vidéo. En ActionScript, il est possible de contrôler avec précision le chargement, la présentation et la lecture d’une vidéo.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La possibilité de lire et manipuler des informations vidéo en ActionScript, au même titre que les autres éléments multimédias (images, texte, animations, etc.) est l’une des principales caractéristiques d’Adobe® Flash® Player et d’Adobe® AIR™. Lorsque vous créez un fichier vidéo Flash (FLV) dans Adobe Flash CS4 Professional, vous avez la possibilité de sélectionner un habillage, ou « enveloppe », comportant les commandes de lecture courantes. Toutefois, vous n’êtes pas limité aux options disponibles. ActionScript offre un contrôle précis du chargement, de l’affichage et de la lecture de la vidéo, et vous pouvez créer votre propre enveloppe ou utiliser une vidéo de façon beaucoup moins traditionnelle. La gestion de la vidéo en ActionScript nécessite de travailler avec une combinaison de plusieurs classes :
La vidéo sur la scène impose diverses restrictions mineures en matière de lecture de vidéo. Si l’application gère ces restrictions, mettez en œuvre l’API StageVideo. Voir « Directives et restrictions » à la page 530.
NetStream représente la source du contenu vidéo (dans ce cas précis, un flux de données vidéo). L’utilisation d’une occurrence de NetStream nécessite d’utiliser également un objet NetConnection, qui assure la connexion avec le fichier vidéo, comme un tunnel qu’emprunteraient les données vidéo.
StageVideo. Pour charger un fichier vidéo externe, vous pouvez charger ce fichier à partir d’un serveur Web standard (téléchargement progressif) ou gérer de la vidéo en flux continu transmise par un serveur spécialisé tel que Flash® Media Server d’Adobe.
Codage Processus de conversion de données vidéo d’un format dans un autre format vidéo. Par exemple, la
Image Elément de base des informations vidéo. Chaque image s’apparente à un cliché photographique représentant
Image-clé Image vidéo qui contient l’ensemble des informations de l’image. Les autres images qui suivent une image-
Métadonnées Informations sur un fichier vidéo intégrées à ce fichier et lues après son chargement. Téléchargement progressif Lorsqu’un fichier vidéo est transmis par un serveur Web standard, les données vidéo sont
Diffusion en continu Pour éviter le téléchargement progressif, il est possible d’utiliser un serveur vidéo spécial pour diffuser de la vidéo sur Internet selon une technique connue sous le nom de diffusion en continu. Avec la diffusion en flux continu, l’ordinateur client ne charge jamais toute la vidéo à la fois. Pour accélérer les délais de chargement, l’ordinateur n’a besoin, à un moment donné, que d’une partie de l’ensemble des informations vidéo. Comme un serveur spécial contrôle la diffusion du contenu vidéo, une partie quelconque de celle-ci peut être transmise à tout moment, et il n’est donc pas nécessaire d’attendre qu’elle soit chargée pour y accéder.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Outre le format vidéo Adobe FLV, Flash Player et Adobe AIR prennent en charge les contenus vidéo et audio codés au format H.264 et HE-AAC des formats de fichier standard MPEG-4. Ces formats diffusent des vidéos de qualité supérieure à des débits inférieurs. Les développeurs peuvent utiliser les outils standard, notamment Adobe Premiere Pro et Adobe After Effects, pour créer et présenter du contenu vidéo de grande qualité. Type
Pour les développeurs, il se traduit par la conversion de la vidéo à la résolution sélectionnée, assurant ainsi une lecture fluide sur la plupart des périphériques. Bien que les résolutions qui exploitent l’accélération matérielle varient d’un périphérique à l’autre, la plupart de ces derniers prend en charge les résolutions standard suivantes. Format
Pour plus d’informations et pour obtenir la liste des paramètres d’encodage dans Adobe Media Encoder CS5, voir Recommendations for encoding H.264 video for Flash Player 10.1 on mobile devices (disponible en anglais uniquement). Remarque : sous iOS, seules les vidéos codées avec les codecs Sorenson Spark et On2 VP6 peuvent être lues à l’aide de la classe Video. Vous pouvez lire les données vidéos H.264 dans le lecteur vidéo du périphérique en accédant à l’URL de la vidéo à l’aide de la fonction flash.net.navigateToURL(). Vous pouvez également lire les données vidéo H.264 à l’aide de la balise <video> sur une page html affichée dans un objet StageWebView.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Flash Player 7 prend en charge les fichiers FLV codés avec le codec vidéo Sorenson™ Spark™. Flash Player 8 prend en charge les fichiers FLV codés avec l’encodeur Sorenson ou On2 VP6 dans Flash Professional 8. Le codec On2 VP6 prend en charge un canal alpha.
MPEG-4. Ces fichiers sont les suivants : F4V, MP4, M4A, MOV, MP4V, 3GP et 3G2, s’ils contiennent de la vidéo H.264 ou de l’audio codé au format HE-AAC v2, ou les deux. H.264 produit une qualité vidéo supérieure à un débit inférieur par rapport au même profil d’encodage dans Sorenson ou On2. HE-AAC v2 est une extension du format AAC, format audio standard défini dans la norme vidéo MPEG-4. HE-AAC v2 utilise les techniques de réplique spectrale de bande (SBR - Spectral Band Replication) et de stéréo paramétrique pour optimiser l’efficacité de l’encodage à des vitesses de transfert inférieures. Le tableau suivant répertorie les codecs pris en charge. Il décrit également le format de fichier SWF correspondant et les versions de Flash Player et d’AIR requises pour les lire : Codec
(version de publication la plus récente prise en charge)
A partir de Flash Player Update 3 (9.0.115.0) et AIR 1.0, Flash Player et AIR prennent en charge le format vidéo Adobe F4V qui découle du format ISO MP4. Les sous-ensembles du format prennent en charge des fonctions diverses. Flash Player s’attend à ce qu’un fichier F4V valide commence par l’une des boîtes de haut niveau suivantes :
La boîte ftyp identifie les fonctions qu’un programme doit prendre en charge pour diffuser un format de fichier particulier.
Les fichiers F4V prennent en charge des entiers multioctets dans un ordre d’octets gros-boutiste, dans lequel l’octet le plus significatif paraît le premier, à l’adresse la plus basse.
Le format de fichier Adobe FLV contient des données audio et vidéo codées pour un acheminement via Flash Player. Vous pouvez utiliser un codeur, tel qu’Adobe Media Encoder ou Sorenson™ Squeeze, pour convertir un fichier vidéo QuickTime ou Windows Media en un fichier FLV. Remarque : vous pouvez créer des fichiers FLV en important la vidéo dans Flash et en l’exportant sous forme de fichier FLV. Vous pouvez utiliser le module d’exportation FLV pour exporter des fichiers FLV à partir des applications de montage vidéo prises en charge. Pour charger des fichiers FLV à partir d’un serveur Web, enregistrez l’extension de fichier et le type MIME auprès de votre serveur Web. Pour ce faire, consultez la documentation du serveur. Le type MIME des fichiers FLV est video/x-flv. Pour plus d’informations, voir « A propos de la configuration de fichier FLV pour l’hébergement sur un serveur » à la page 522. Pour plus d’informations sur les fichiers FLV, voir « Rubriques avancées relatives aux fichiers vidéo » à la page 521.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’utilisation des fichiers vidéo externes offre certaines fonctionnalités qui ne sont pas disponibles avec l’utilisation de la vidéo importée :
Présentation de la classe Video Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe Video permet d’afficher un flux vidéo en direct dans une application sans l’imbriquer dans votre fichier SWF. Vous pouvez capturer et lire du contenu vidéo en direct à l’aide de la méthode Camera.getCamera(). Vous pouvez également utiliser la classe Video pour lire les fichiers vidéo en HTTP ou sur le système de fichiers local. Il existe plusieurs façons d’utiliser la classe Video dans vos projets.
• Utilisation de la commande VideoDisplay. Remarque : les occurrences d’un objet Video sur la scène sont des occurrences de la classe Video. Bien que la classe Video se trouve dans le package flash.media, elle hérite de la classe flash.display.DisplayObject. Par conséquent, toutes les fonctionnalités des objets d’affichage (transformation de matrice et filtres par exemple) s’appliquent aussi aux occurrences de l’objet Video. Pour plus d’informations, voir « Manipulation des objets d’affichage » à la page 180, ainsi que les chapitres « Utilisation de la géométrie » à la page 218 et « Filtrage des objets d’affichage » à la page 276.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le chargement de fichiers vidéo à l’aide des classes NetStream et NetConnection s’effectue en plusieurs étapes. Il est recommandé d’ajouter l’objet Video à la liste d’affichage, de joindre l’objet NetStream à l’occurrence de l’objet Video et d’appeler la méthode play() de l’objet NetStream dans l’ordre spécifié : 1 Créez un objet NetConnection. Dans le cas d’une connexion à un fichier vidéo local ou à un fichier qui n’utilise pas
Dernière mise à jour le 27/4/2013
La classe NetStream comporte quatre méthodes principales pour contrôler la lecture vidéo : pause() : interrompt la lecture d’un flux vidéo. Si la lecture de la vidéo est déjà interrompue, l’appel de cette méthode
Remarque : la méthode play() ne reprend pas la lecture, elle est destinée au chargement de fichiers vidéo. L’exemple suivant montre comment contrôler la lecture d’une vidéo à l’aide de divers boutons. Pour exécuter cet exemple, créez un document et ajoutez quatre occurrences de boutons à l’espace de travail (pauseBtn, playBtn, stopBtn et togglePauseBtn) :
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour afficher le début et la fin d’un flux vidéo, vous devez ajouter à l’occurrence de NetStream un écouteur pour l’événement netStatus. L’exemple suivant montre comment écouter les divers codes pendant la lecture de la vidéo : ns.addEventListener(NetStatusEvent.NET_STATUS, statusHandler); function statusHandler(event:NetStatusEvent):void { trace(event.info.code) }
Flash Player et AIR vous permettent de créer une application plein écran pour la lecture de votre vidéo et prennent en charge la mise à l’échelle de la vidéo au mode plein écran. Pour le contenu AIR qui s’exécute en mode plein écran sur le poste de travail, les options économiseur d’écran et économie d’énergie du système sont désactivées lors de la lecture jusqu’à ce que le signal vidéo s’arrête ou que l’utilisateur quitte le mode plein écran. Pour plus d’informations sur l’utilisation du mode plein écran, voir « Utilisation du mode Plein écran » à la page 173. Activation du mode plein écran pour Flash Player dans un navigateur Avant que vous ne puissiez implémenter le plein écran pour Flash Player dans un navigateur, activez-le via le modèle de publication de votre application. Les modèles qui permettent le mode plein écran comprennent les balises <object> et <embed>, qui contiennent un paramètre allowFullScreen. L’exemple suivant affiche le paramètre allowFullScreen dans une balise <embed>.
Pour le contenu de Flash Player s’exécutant dans un navigateur, le mode plein écran de la vidéo est activé en réponse à un clic de souris ou à une pression sur une touche. Par exemple, vous pouvez activer le mode plein écran lorsque l’utilisateur clique sur un bouton appelé Plein écran ou sélectionne une commande Plein écran dans un menu contextuel. Pour répondre à l’utilisateur, ajoutez un écouteur d’événement à l’objet sur lequel se produit l’action. Le code suivant ajoute un écouteur d’événement à un bouton sur lequel l’utilisateur clique pour accéder au mode plein écran : var fullScreenButton:Button = new Button(); fullScreenButton.label = "Full Screen"; addChild(fullScreenButton); fullScreenButton.addEventListener(MouseEvent.CLICK, fullScreenButtonHandler); function fullScreenButtonHandler(event:MouseEvent) { stage.displayState = StageDisplayState.FULL_SCREEN; } La propriété fullScreenSourceRect vous permet de spécifier une zone particulière de la scène en vue de l’afficher en mode plein écran. Définissez tout d’abord le rectangle que vous souhaitez afficher en mode plein écran. Ensuite, affectez-le à la propriété Stage.fullScreenSourceRect. Cette version de la fonction fullScreenButtonHandler() ajoute deux lignes supplémentaires de code qui n’activent le plein écran que pour la vidéo.
Tout utilisateur peut désactiver le mode plein écran à l’aide de l’un des raccourcis clavier, notamment en appuyant sur la touche Echap. En ActionScript, vous pouvez désactiver le mode plein écran en définissant la propriété Stage.displayState sur StageDisplayState.NORMAL. Dans l’exemple suivant, le code désactive le mode plein écran lorsque l’événement netStatus de NetStream.Play.Stop se produit. videoStream.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler); private function netStatusHandler(event:NetStatusEvent) { if(event.info.code == "NetStream.Play.Stop") stage.displayState = StageDisplayState.NORMAL; } Pour plus d’informations sur l’accélération matérielle en mode Plein écran, voir « Utilisation du mode Plein écran » à la page 173. Pour plus d’informations sur StageVideo, voir « Présentation à accélération matérielle par le biais de la classe StageVideo » à la page 528.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour effectuer une lecture en flux continu à partir d’un serveur Flash Media Server, vous pouvez utiliser les classes NetConnection et NetStream afin d’établir la connexion avec une occurrence de serveur distant et lire le flux spécifié. Pour spécifier un serveur RTMP (Real-Time Messaging Protocol), il suffit de transmettre l’URL RTMP désirée, par exemple « rtmp://localhost/appName/appInstance » à la méthode NetConnection.connect() au lieu de lui transmettre la valeur null. Pour lire un flux vidéo direct ou enregistré à partir du serveur Flash Media Server spécifié, passez soit un identifiant (pour le signal vidéo en direct publié par NetStream.publish()), soit le nom du fichier enregistré, à la méthode NetStream.play().
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Si vous souhaitez créer des applications plus complexes avec des objets Video ou Camera, Flash Media Server (FMS) offre diverses possibilités de diffusion de flux multimédia ainsi qu’un environnement de développement pour créer des applications multimédia et les distribuer à l’intention d’un public très large. Cette combinaison permet aux développeurs de créer des applications telles que vidéo à la demande, diffusion d’événements en direct sur le Web et diffusion en flux continu MP3, mais aussi blog vidéo, vidéomessagerie ou conversation multimédia. Pour plus d’informations, voir la documentation de Flash Media Server disponible en ligne à l’adresse suivante : www.adobe.com/go/learn_fms_docs_fr.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous pouvez intégrer des points de repère dans un fichier vidéo F4V ou FLV durant le codage. A l’origine, les points de repère étaient intégrés dans des films pour signaler visuellement au projectionniste que la bobine s’approchait de la fin. Dans les formats vidéo Adobe F4V et FLV, un point de repère vous permet de déclencher une ou plusieurs actions dans votre application au moment où il survient dans le flux vidéo. Vous pouvez utiliser plusieurs types de points de repère avec Flash Video. ActionScript permet d’interagir avec les points de repère que vous intégrez dans un fichier vidéo lorsque vous le créez.
FLVPlayback de Flash. Les points de repère ActionScript sont des points de repère externes que vous créez et auxquels vous accédez à l’aide du code ActionScript. Du code permet de déclencher ces points de repère en fonction de la lecture vidéo. Ces points de repère sont moins précis que les points de repère intégrés (jusqu’à un dixième de seconde), car le lecteur vidéo les analyse séparément. Si vous avez l’intention de créer une application dans laquelle il sera possible d’atteindre un point de repère, créez et intégrez les points de repère lors de l’encodage du fichier, au lieu d’utiliser des points de repère ActionScript. Il est préférable d’intégrer les points de repère dans le fichier FLV, car ils sont alors plus précis. Les points de repère de navigation créent une image-clé à l’emplacement spécifié, pour permettre de déplacer la tête de lecture du lecteur vidéo à cet emplacement. Vous pouvez définir des points particuliers dans un fichier vidéo pour permettre aux utilisateurs d’atteindre un emplacement précis. Par exemple, si votre vidéo contient plusieurs chapitres et segments, vous pouvez la contrôler en intégrant des points de repère de navigation dans le fichier vidéo. Pour plus d’informations sur le codage de fichiers vidéo Adobe avec des points de repère, voir « Intégration de points de repère » dans Utilisation de Flash. Vous pouvez accéder aux paramètres des points de repère à l’aide de code ActionScript. Les paramètres de points de repère font partie de l’objet d’événement reçu du gestionnaire de rappel. Le gestionnaire d’événement NetStream.onCuePoint permet de déclencher certaines actions dans votre code lorsque le fichier FLV atteint un point de repère spécifique. Pour synchroniser une action avec un point de repère dans un fichier vidéo F4V, vous devez récupérer les données de point de repère des fonctions de rappel onMetaData() ou onXMPData() et déclencher le point de repère à l’aide de la classe Timer dans ActionScript 3.0. Pour plus d’informations sur les points de repère de F4V, voir « Utilisation d’onXMPData() » à la page 514. Pour plus d’informations sur l’utilisation des points de repère et des métadonnées, voir « Ecriture de méthodes de rappel pour les métadonnées et les points de repère » à la page 502.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous pouvez déclencher des actions au sein de votre application lorsque le lecteur reçoit des métadonnées spécifiques ou lorsque des points de repère particuliers sont atteints. Lorsque ces événements se produisent, vous devez utiliser des méthodes de rappel spécifiques en tant que gestionnaires d’événements. La classe NetStream spécifie les événements de métadonnées suivants qui se produisent lors de la lecture : onCuePoint (fichiers FLV uniquement), onImageData, onMetaData, onPlayStatus, onTextData et onXMPData. Si vous ne créez pas de méthodes de rappel pour ces gestionnaires, le moteur d’exécution Flash risque de générer des erreurs. Par exemple, le code ci-dessous lit le fichier FLV video.flv situé dans le même dossier que le fichier SWF :
Dernière mise à jour le 27/4/2013
Utilisation de la vidéo
{ trace("metadata"); } Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le code suivant définit la propriété client de l’objet NetStream comme étant une classe personnalisée, CustomClient, qui définit des gestionnaires pour les méthodes de rappel : var nc:NetConnection = new NetConnection(); nc.connect(null); var ns:NetStream = new NetStream(nc); ns.client = new CustomClient(); ns.play("video.flv"); var vid:Video = new Video(); vid.attachNetStream(ns); addChild(vid);
{ public class CustomClient Dernière mise à jour le 27/4/2013
Etendre la classe NetStream et lui ajouter des méthodes pour gérer les méthodes de rappel Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le code suivant crée une occurrence de la classe CustomNetStream, qui sera définie ultérieurement : var ns:CustomNetStream = new CustomNetStream(); ns.play("video.flv"); var vid:Video = new Video(); vid.attachNetStream(ns); addChild(vid);
{ import flash.net.NetConnection; import flash.net.NetStream; public class CustomNetStream extends NetStream { private var nc:NetConnection; public function CustomNetStream() La classe DynamicCustomNetStream contient le code suivant :
Dernière mise à jour le 27/4/2013
Si les gestionnaires de rappel de onMetaData ou onCuePoint sont appelés et qu’il n’existe pas de méthode pour gérer le rappel, aucune erreur n’est générée. Pour gérer ces gestionnaires de rappel, créez des méthodes onMetaData() et onCuePoint() dans votre code, comme dans le fragment de code suivant : function onMetaData(infoObject:Object):void { trace("metadata"); } function onCuePoint(infoObject:Object):void Les méthodes de rappel NetStream vous permettent de capturer et de traiter les événements de point de repère et de métadonnées lorsque la vidéo est en cours de lecture.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le tableau ci-dessous décrit les méthodes de rappel que vous pouvez utiliser pour capturer les points de repère F4V et FLV dans Flash Player et AIR. Moteur d’exécution
Vous pouvez utiliser les fonctions OnMetaData() et OnXMPData() pour accéder à des informations sur les métadonnées dans votre fichier vidéo, y compris les points de repère.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Ces métadonnées comprennent des informations sur le fichier vidéo (durée, largeur et hauteur d’image, cadence). Les informations de métadonnées ajoutées à votre fichier vidéo dépendent du logiciel que vous utilisez pour coder le fichier vidéo.
Dernière mise à jour le 27/4/2013
Dernière mise à jour le 27/4/2013
Pour plus d’informations sur XMP, voir :
• www.adobe.com/devnet/xmp/ Utilisation des métadonnées de l’image Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’événement onImageData envoie les données d’image sous la forme d’un tableau d’octets par l’intermédiaire d’un canal de données AMF0. Les données peuvent être au format JPEG, PNG ou GIF. Définissez une méthode de rappel onImageData() pour traiter ces informations, de la même manière que vous définiriez des méthodes de rappel pour onCuePoint et onMetaData. L’exemple suivant accède aux données d’image et les affiche à l’aide d’une méthode de rappel onImageData() : public function onImageData(imageData:Object):void { // display track number trace(imageData.trackid); var loader:Loader = new Loader(); //imageData.data is a ByteArray object loader.loadBytes(imageData.data); addChild(loader); L’événement onTextData envoie des données de texte par le biais d’un canal de données AMF0. Les données de texte sont au format UTF-8 et contiennent des informations supplémentaires sur la mise en forme basées sur la spécification Timed Text 3GP. Cette spécification définit un format de sous-titrage normalisé. Définissez une méthode de rappel onTextData() pour traiter ces informations, de la même manière que vous définiriez des méthodes de rappel pour onCuePoint ou onMetaData. Dans l’exemple suivant, la méthode onTextData() affiche le numéro d’identification de la piste, ainsi que le texte correspondant à la piste. public function onTextData(textData:Object):void { // display the track number trace(textData.trackid); // displays the text, which can be a null string, indicating old text Dernière mise à jour le 27/4/2013
Un objet NetStream distribue les événements répertoriés dans le tableau ci-dessous, en fonction du type de média en cours de lecture : Evénement
De même, les événements NetStream.Play.Transition et NetStream.Play.TransitionComplete ne sont pas distribués pour le téléchargement progressif ou le média HTTP. La commutation dynamique du taux d’échantillonnage est une fonction RTMP. Si un lecteur vidéo qui utilise le flux HTTP prend en charge une fonction similaire, il est alors en mesure de synthétiser et de distribuer des événements de transition.
Adobe Developer Connection: Measuring video consumption in Flash (disponible en anglais uniquement)
Les événements mediaTypeData fournissent des métadonnées et des informations de données XMP. L’événement Netstream.Play.Complete est distribué en tant qu’événement mediaTypeData. D’autres données intégrées au flux sont également disponibles via les événements mediaTypeData, notamment les points de repère, le texte et les images.
Utilisation de la vidéo
{ import flash.events.NetDataEvent; import flash.events.NetMonitorEvent; import flash.events.NetStatusEvent; import flash.net.NetMonitor; import flash.net.NetStream; public class NetStreamEventMonitor { private var netmon:NetMonitor; private var heartbeat:Timer = new Timer( 5000 ); public function NetStreamEventMonitor() à la propriété pageDomain de la classe Security. L’adresse URL complète n’est pas divulguée afin d’assurer la sécurité et la confidentialité de l’utilisateur. Le domaine de la page est disponible via la propriété pageDomain statique de la classe Security : var domain:String = Security.pageDomain;
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les rubriques suivantes abordent certains problèmes d’utilisation des fichiers FLV.
A propos de la configuration de fichier FLV pour l’hébergement sur un serveur Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour utiliser des fichiers FLV, il peut être nécessaire de configurer votre serveur pour le format de fichier FLV. Le protocole MIME (Multipurpose Internet Mail Extensions) est une spécification de données normalisée qui permet d’envoyer des fichiers non ASCII via des connexions Internet. Les navigateurs Web et les clients de courrier électronique sont configurés pour interpréter de nombreux types MIME afin qu’ils puissent envoyer et recevoir de la vidéo, de l’audio, des graphiques et du texte formaté. Pour charger des fichiers FLV à partir d’un serveur Web, il peut être nécessaire d’enregistrer l’extension de fichier et le type MIME auprès de votre serveur Web. Pour plus d’informations, consultez la documentation du serveur. Le type MIME des fichiers FLV est video/x-flv. Les informations complètes du type de fichier FLV se présentent comme suit :
• Extension du fichier : .flv • Paramètres requis : aucun • Paramètres facultatifs : aucun • Considérations sur l’encodage : les fichiers FLV sont binaires, et une partie des applications peut nécessiter la définition du sous-type application/octet-stream
• Spécifications publiées : www.adobe.com/go/video_file_format_fr Microsoft a changé la façon dont le multimédia en flux continu est géré par le serveur Web 6.0 IIS (Microsoft Internet Information Services) par rapport à ses versions antérieures. Les versions antérieures d’IIS ne nécessitent aucune modification pour diffuser en continu de la vidéo Flash. Dans IIS 6.0, le serveur Web fourni par défaut avec Windows 2003, le serveur nécessite un type MIME pour reconnaître que les fichiers FLV sont des flux continus multimédia. Lorsque des fichiers SWF qui diffusent des fichiers FLV externes sont placés sur un serveur Microsoft Windows Server® 2003 et sont affichés dans un navigateur, le fichier SWF est lu correctement, mais la vidéo FLV n’est pas diffusée en continu. Ce problème a une incidence sur tous les fichiers FLV placés sur le serveur Windows Server 2003, y compris les fichiers créés avec des versions antérieures de l’outil de programmation Flash et le Kit Macromedia Flash Video Kit pour Dreamweaver MX 2004 d’Adobe. Ces fichiers fonctionnent correctement si vous les testez avec d’autres systèmes d’exploitation. Pour plus d’informations sur la méthode de configuration de Microsoft Windows 2003 et Microsoft IIS Server 6.0 pour diffuser en continu de la vidéo FLV, voir la page www.adobe.com/go/tn_19439_fr.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Si vous tentez de lire un fichier FLV local à partir d’un lecteur non système sur un ordinateur Apple® Macintosh® avec un chemin qui utilise une barre oblique (/), il ne sera pas lu. Les lecteurs non système sont par exemple les lecteurs de CDROM, les disques durs partitionnés, les supports de stockage amovibles, les périphériques de stockage connectés, etc. Remarque : la raison de cet échec est une limitation du système d’exploitation, et non pas de Flash Player ni d’AIR. Pour qu’un fichier FLV puisse être lu à partir d’un lecteur non système sur un Macintosh, faites-y référence à l’aide d’un chemin absolu utilisant une notation à deux points (:) au lieu d’une notation à barres obliques (/). La liste suivante montre la différence entre les deux sortes de notation :
• Actualisation de la position de la tête de lecture en fonction de la progression dans le fichier vidéo • Détection et analyse des métadonnées d’un fichier vidéo • Gestion de codes spécifiques dans un flux Internet • Chargement, lecture, mise en pause et arrêt d’un fichier FLV chargé dynamiquement • Redimensionnement d’un objet vidéo dans la liste d’affichage en fonction des métadonnées du flux reçu Pour obtenir les fichiers d’application de cet exemple, voir www.adobe.com/go/learn_programmingAS3samples_flash_fr. Les fichiers de l’application Video Jukebox se trouvent dans le dossier Samples/VideoJukebox. L’application se compose des fichiers suivants : Fichier
Le fichier externe playlist.xml contient la liste des vidéos à charger et leur ordre de lecture. Pour charger ce fichier XML, utilisez un objet URLLoader et un objet URLRequest, comme dans le code ci-dessous : uldr = new URLLoader(); uldr.addEventListener(Event.COMPLETE, xmlCompleteHandler); uldr.load(new URLRequest(PLAYLIST_XML_URL));
{ playlist = XML(event.target.data); videosXML = playlist.video; main(); } L’objet XML playlist contient les données XML brutes du fichier externe, alors que videosXML est un objet XMLList qui ne contient que les nœuds vidéo. Le fragment de code suivant est un exemple de contenu du fichier playlist.xml : <videos> <video url="video/caption_video.flv" /> Pour créer l’interface utilisateur, faites glisser cinq occurrences de l’objet Button sur la liste d’affichage et donnez-leur les noms d’occurrence suivants : playButton, pauseButton, stopButton, backButton et forwardButton. Pour chacune de ces occurrences de Button, affectez un gestionnaire pour l’événement click, comme dans le fragment de code suivant : playButton.addEventListener(MouseEvent.CLICK, buttonClickHandler); pauseButton.addEventListener(MouseEvent.CLICK, buttonClickHandler); stopButton.addEventListener(MouseEvent.CLICK, buttonClickHandler); backButton.addEventListener(MouseEvent.CLICK, buttonClickHandler); forwardButton.addEventListener(MouseEvent.CLICK, buttonClickHandler);
{ switch (event.currentTarget) { case playButton: ns.resume(); break; case pauseButton: ns.togglePause(); break; case stopButton: ns.pause(); ns.seek(0); break; case backButton: playPreviousVideo(); break; case forwardButton: playNextVideo(); break; Ajoutez ensuite une occurrence de ProgressBar à la liste d’affichage, et donnez à cette occurrence le nom positionBar. Donnez à sa propriété mode la valeur « manual », comme ci-dessous : positionBar.mode = ProgressBarMode.MANUAL;
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lorsque Flash Player détecte des métadonnées dans l’une des vidéos chargées, le gestionnaire de rappel onMetaData() est appelé pour la propriété client de l’objet NetStream. Le code suivant initialise un Object et configure le gestionnaire de rappel spécifié : client = new Object(); client.onMetaData = metadataHandler;
Video sur la scène est ensuite redimensionné selon la taille renvoyées par les métadonnées. Enfin, l’occurrence de positionBar de la barre de progression est déplacée et redimensionnée en fonction de la taille de la vidéo en cours. Le code suivant est celui de la méthode metadataHandler() : private function metadataHandler(metadataObj:Object):void { meta = metadataObj; vid.width = meta.width; vid.height = meta.height; positionBar.move(vid.x, vid.y + vid.height); positionBar.width = vid.width; }
A chaque exécution de Timer, l’occurrence de la barre de progression positionBar actualise sa position en appelant la méthode setProgress() de la classe ProgressBar, et l’occurrence de Label positionLabel est actualisée avec le temps écoulé et la durée totale de la vidéo active. private function timerHandler(event:TimerEvent):void { try { positionBar.setProgress(ns.time, meta.duration); positionLabel.text = ns.time.toFixed(1) + " of " meta.duration.toFixed(1) + " seconds"; } catch (error:Error) Contrôle du volume de la vidéo Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous pouvez contrôler le volume audio de la vidéo chargée dynamiquement par le biais de la propriété soundTransform de l’objet NetStream. L’application Video jukebox permet de modifier le volume en changeant la valeur de l’occurrence de Slider volumeSlider. Le code suivant montre comment changer le volume en affectant la valeur du composant Slider à un objet SoundTransform qui est lui-même affecté à la propriété soundTransform de l’objet NetStream : private function volumeChangeHandler(event:SliderEvent):void { volumeTransform.volume = event.value; ns.soundTransform = volumeTransform; }
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le reste de l’application contrôle la lecture de la vidéo lorsque la fin du flux vidéo est atteinte ou lorsque l’utilisateur change de vidéo. La méthode suivante obtient l’adresse URL de la vidéo à partir de l’objet XMLList pour l’index sélectionné : private function getVideo():String { return videosXML[idx].@url; }
Flash Player améliore les performances vidéo par le biais d’une accélération matérielle pour le décodage H.264. Vous pouvez optimiser ces performances à l’aide de l’API StageVideo. La vidéo sur la scène permet à l’application d’exploiter la présentation à accélération matérielle. Les moteurs d’exécution suivants prennent en charge l’API StageVideo :
Remarque : dans Flash Player 11.4/AIR 3.4 et les versions ultérieures, vous pouvez utiliser l'entrée caméra avec StageVideo. Vous trouverez le code source à télécharger et d’autres informations relatives à la fonction de vidéo sur la scène à l’adresse Getting Started with Stage Video (disponible en anglais uniquement). Pour consulter un didacticiel de démarrage rapide, voir Working with Stage Video (disponible en anglais uniquement).
La présentation à accélération matérielle, qui comprend la mise à l’échelle de la vidéo, la conversion de la couleur et la fusion, exploite l’optimisation des performances assurée par le décodage à accélération matérielle. Sur les périphériques qui gèrent l’accélération par processeur graphique (matérielle), vous disposez d’un objet flash.media.StageVideo pour traiter la vidéo directement sur le matériel du périphérique. Un traitement direct permet à l’unité centrale d’exécuter d’autres tâches pendant que le processeur graphique gère la vidéo. La classe Video existante fait en revanche appel à la présentation logicielle. La présentation logicielle est exécutée dans l’unité centrale et sollicite parfois une proportion élevée des ressources du système. A l’heure actuelle, peu de périphériques prennent en charge l’accélération par processeur graphique complète. La vidéo sur la scène permet toutefois aux applications d’exploiter pleinement l’accélération matérielle éventuellement intégrée.
La classe StageVideo ne rend pas obsolète la classe Video. L’association de ces deux classes assure l’expérience optimale de visualisation de la vidéo autorisée par les ressources du périphérique à un moment donné. L’application exploite l’accélération matérielle en écoutant les événements appropriés et bascule entre les classes StageVideo et Video en fonction des besoins. La classe StageVideo impose diverses restrictions en matière d’utilisation de la vidéo. Avant de mettre en œuvre la classe StageVideo, passez en revue les directives et assurez-vous que l’application est en mesure de les prendre en charge. Si vous acceptez les restrictions, utilisez la classe StageVideo à chaque fois que Flash Player détecte qu’une présentation à accélération matérielle est disponible. Voir « Directives et restrictions » à la page 530.
Le modèle de vidéo sur la scène permet à Flash Player de séparer la vidéo de la liste d’affichage. Flash Player divise l’affichage composite entre deux plans Z : Plan de vidéo sur la scène Le plan de vidéo sur la scène est situé en arrière-plan. Il n’affiche que la vidéo à accélération matérielle. Ce plan n’est de ce fait disponible que si l’accélération matérielle n’est pas prise en charge par le périphérique ou qu’elle n’est pas intégrée à ce dernier. En ActionScript, les objets StageVideo traitent les vidéos lues sur le plan de la vidéo sur la scène. Plan associé à la liste d’affichage de Flash Les entités qui figurent dans la liste d’affichage de Flash sont combinées sur
L’objet StageVideo apparaît dans une zone rectangulaire sans rotation de l’écran, alignée sur la fenêtre. Il est impossible de superposer les objets derrière le plan de la vidéo sur la scène. Le plan associé à la liste d’affichage de Flash permet toutefois de superposer d’autres graphiques au plan de la vidéo sur la scène. La vidéo sur la scène et la liste d’affichage s’exécutent simultanément. Vous pouvez de ce fait combiner les deux mécanismes pour créer un effet visuel unifié qui utilise deux plans discrets. Vous pouvez, par exemple, réserver le plan avant aux contrôles de lecture associés à la vidéo sur la scène qui s’exécute en arrière-plan.
Dans les applications Flash Player, la mise en œuvre de l’accélération matérielle de la vidéo se compose de deux étapes : 1 Encodage de la vidéo au format H.264 2 Mise en œuvre de l’API StageVideo
La vidéo sur la scène élimine la rétro-lecture du processeur graphique à l’unité centrale. En d’autres termes, le processeur graphique n’envoie plus d’images décodées à l’unité centrale en vue de leur composition avec les objets de la liste d’affichage. Il fusionne plutôt directement à l’écran les images décodées et rendues, derrière les objets issus de la liste d’affichage. Cette technique sollicite moins l’unité centrale et la mémoire tout en assurant une fidélité accrue des pixels.
« Présentation des formats vidéo » à la page 490
Si la vidéo est exécutée en mode Plein écran, la vidéo sur la scène est toujours disponible, sous réserve que le périphérique prenne en charge l’accélération matérielle. Flash Player s’exécute toutefois aussi au sein d’un navigateur. Dans le contexte du navigateur, le paramètre wmode affecte la disponibilité de la vidéo sur la scène. Tentez d’utiliser systématiquement le paramètre wmode="direct" si vous souhaitez faire appel à la vidéo sur la scène. La vidéo sur la scène est incompatible avec d’autres paramètres wmode si le mode Plein écran est désactivé. Cette restriction signifie qu’à l’exécution, la disponibilité continue de la vidéo sur la scène n’est pas assurée. Si, par exemple, l’utilisateur quitte le mode Plein écran alors que la vidéo sur la scène est en cours de lecture, le contexte de cette dernière correspond à nouveau au navigateur. Si le paramètre wmode du navigateur n’est pas défini sur « direct », la vidéo sur la scène risque de n’être soudainement plus disponible. Flash Player communique les changements de contexte de lecture aux applications par le biais d’une série d’événements. Si vous mettez en œuvre l’API StageVideo, conservez un objet Video à titre d’objet de secours au cas où la vidéo de la scène ne serait plus disponible. En raison de son lien direct avec le matériel, la vidéo sur la scène interdit certaines fonctionnalités vidéo. La vidéo sur la scène impose les contraintes suivantes :
• La zone d’affichage vidéo ne peut être qu’un rectangle. Il est impossible d’utiliser des zones d’affichage plus avancées, telles que des formes elliptiques ou irrégulières.
• Il est impossible de placer la vidéo dans le cache de bitmaps ou d’utiliser BitmapData pour y accéder.
• Il est impossible d’appliquer des filtres à la vidéo. • Il est impossible d’appliquer des transformations de couleur à la vidéo. • Il est impossible d’appliquer une valeur alpha à la vidéo. • Les modes de fusion que vous appliquez aux objets de la liste d’affichage ne s’appliquent pas à la vidéo sur la scène. • Vous pouvez positionner la vidéo uniquement sur les limites de pixels pleines. • Bien que le rendu par processeur graphique soit optimisé en fonction du matériel du périphérique indiqué, il n’est pas identique « au pixel près » d’un périphérique à un autre. De légères variations risquent de survenir en raison des différences de pilotes et de plates-formes.
BT.601 pour assurer un affichage rapide.
WMODE n’a aucun effet dans Safari 4 ou version ultérieure, et IE 9 ou une version ultérieure. Dans la plupart des cas, ces restrictions n’affectent pas les lecteurs vidéo. Si vous êtes prêt à les accepter, utilisez dans la mesure du possible la vidéo sur la scène.
« Utilisation du mode Plein écran » à la page 173
La vidéo sur la scène est un mécanisme intégré au moteur d’exécution qui optimise la lecture de vidéos et les performances des périphériques. Le moteur d’exécution crée et gère ce mécanisme. En tant que développeur, il vous incombe de configurer l’application de sorte à l’exploiter pleinement. Pour utiliser la vidéo sur la scène, vous mettez en œuvre une structure de gestionnaires d’événement qui détectent la disponibilité ou la non-disponibilité de la vidéo sur la scène. Lorsque vous êtes averti de la disponibilité de la vidéo sur la scène, vous récupérez un objet StageVideo de la propriété Stage.stageVideos. Le moteur d’exécution insère dans l’objet Vector un ou plusieurs objets StageVideo. Vous pouvez alors afficher une vidéo en flux continu par le biais de l’un des objets StageVideo fournis, plutôt qu’un objet Video. Sur Flash Player, lorsque vous êtes averti que la vidéo sur la scène n’est plus disponible, réactivez l’utilisation d’un objet Video pour afficher le flux vidéo. Remarque : il est impossible de créer des objets StageVideo.
La propriété Stage.stageVideos est un objet Vector qui permet d’accéder aux occurrences de StageVideo. Selon les ressources matérielles et système disponibles, ce vecteur peut contenir jusqu’à quatre objets StageVideo. Il est possible de limiter à un ou zéro les périphériques mobiles. Si la vidéo sur la scène n’est pas disponible, ce vecteur ne contient pas d’objet. Pour éviter les erreurs d’exécution, veillez à n’accéder aux membres de cet objet vectoriel que si l’événement StageVideoAvailability le plus récent indique la disponibilité de la vidéo sur la scène.
StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY Evénement envoyé en cas de modification de la propriété Stage.stageVideos. La propriété StageVideoAvailabilityEvent.availability indique soit AVAILABLE, soit UNAVAILABLE. Cet événement permet de déterminer si la propriété stageVideos contient des objets StageVideo, plutôt que de vérifier directement la longueur de l’objet vectoriel Stage.stageVideos.
Important : étant donné qu’elles ne figurent pas dans la liste d’affichage standard, les coordonnées issues de l’objet StageVideo cible utilisent les coordonnées Stage. VideoEvent.RENDER_STATE Evénement envoyé si un objet Video est en cours d’utilisation. Il indique le type de décodage en cours d’utilisation (matériel ou logiciel). Si cet événement indique un décodage à accélération matérielle, utilisez de préférence un objet StageVideo. L’événement Video cible contient les propriétés videoWidth et videoHeight, dont l’utilisation est adaptée au redimensionnement de la fenêtre d’affichage de la vidéo.
Procédez comme suit pour mettre en œuvre la fonction StageVideo : 1 Ecoutez l’événement StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY pour savoir quand l’objet
StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY » à la page 533. 2 Si l’événement StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY indique que la vidéo sur la scène
à un objet StageVideo. 3 Associez un objet NetStream à l'aide de StageVideo.attachNetStream() ou associez un objet Camera à l'aide de StageVideo.attachCamera().
5 Ecoutez l’événement StageVideoEvent.RENDER_STATE sur l’objet StageVideo afin de déterminer l’état de lecture
VideoEvent.RENDER_STATE » à la page 535. 6 Ecoutez l’événement VideoEvent.RENDER_STATE sur l’objet Video. Cet événement indique les mêmes états que
StageVideoEvent.RENDER_STATE et VideoEvent.RENDER_STATE » à la page 535.
Configurez les écouteurs StageVideoAvailabilityEvent et VideoEvent lors de l’initialisation de l’application. Vous pouvez, par exemple, initialiser ces écouteurs dans le gestionnaire d’événement flash.events.Event.ADDED_TO_STAGE. Cet événement assure la visibilité de l’application sur la scène :
Si la propriété StageVideoAvailabilityEvent.availability est définie sur StageVideoAvailability.UNAVAILABLE, n’utilisez pas l’objet StageVideo et n’accédez pas à l’objet vectoriel Stage.stageVideos. Associez dans ce cas l’objet NetStream à un objet Video. Ajoutez enfin l’objet StageVideo ou Video à la scène et appelez la méthode NetStream.play(). Le code suivant illustre le traitement de l’événement StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY :
Utilisation des événements StageVideoEvent.RENDER_STATE et VideoEvent.RENDER_STATE Les objets StageVideo et Video envoient des événements qui indiquent aux applications tout changement de l’environnement d’affichage. Ces événements sont StageVideoEvent.RENDER_STATE et VideoEvent.RENDER_STATE. Un objet StageVideo ou Video distribue un événement d’état de rendu lorsqu’un objet NetStream est associé et que sa lecture débute. Il envoie également cet événement lorsque l’environnement d’affichage est modifié (en cas de redimensionnement de la fenêtre d’affichage de la vidéo, par exemple). Ces notifications permettent de réinitialiser la fenêtre d’affichage sur les valeurs videoHeight et videoWidth actuelles de l’objet événement cible. Les états de rendu indiqués sont les suivants :
(Performances les moins satisfaisantes. Elles sont dégradées en mode Plein écran.)
La vidéo sur la scène fait appel aux capacités matérielles sous-jacentes pour prendre en charge les espaces colorimétriques. Un contenu SWF peut fournir des métadonnées qui indiquent l’espace colorimétrique préféré. Le matériel graphique du périphérique détermine toutefois s’il est possible d’utiliser l’espace colorimétrique. Un périphérique peut prendre en charge plusieurs espaces colorimétriques, tandis qu’un autre périphérique n’en prend en charge aucun. Si le matériel ne prend pas en charge l’espace colorimétrique requis, Flash Player tente d’identifier la correspondance la plus proche parmi les espaces colorimétriques gérés. Pour déterminer les espaces colorimétriques pris en charge par le matériel, faites appel à la propriété StageVideo.colorSpaces. Cette propriété renvoie la liste des espaces colorimétriques pris en charge dans un vecteur String : var colorSpace:Vector.<String> = stageVideo.colorSpaces();
Utilisation de la vidéo
StageVideoEvent.colorSpace. Vérifiez cette propriété dans le gestionnaire associé à l’événement StageVideoEvent.RENDER_STATE : var currColorSpace:String; //StageVideoEvent.RENDER_STATE event handler private function stageVideoRenderState(event:Object):void { Dernière mise à jour le 27/4/2013
ActionScript l’affichage et la manipulation de ces données. La classe Camera est le mécanisme intégré à ActionScript permettant d’utiliser un ordinateur ou une caméra. Sur les périphériques mobiles, vous pouvez également utiliser la classe CameraUI. La classe CameraUI ouvre une application de caméra indépendante pour permettre à l’utilisateur de capturer un cliché ou d’enregistrer une vidéo. Lorsque l’utilisateur a terminé, votre application peut accéder à l’image ou à la vidéo via un objet MediaPromise.
Christian Cantrell : How to use CameraUI in a Cross-platform Way (disponible en anglais uniquement) L’objet Camera permet d’établir une connexion avec la caméra locale de l’utilisateur et de diffuser le signal vidéo soit localement (à destination de l’utilisateur lui-même) ou à destination d’un serveur tel que Flash Media Server. La classe Camera permet d’accéder aux informations suivantes sur la caméra de l’utilisateur :
• Installation d’une caméra ou non • Si Flash Player est autorisé ou non à accéder à la caméra de l’utilisateur • Caméra active • Largeur et hauteur de la vidéo en cours de capture, en pixels La classe Camera fournit les méthodes et les propriétés qui permettent d’utiliser les objets Camera. Par exemple, la propriété statique Camera.names contient le tableau des noms des caméras actuellement installées sur l’ordinateur. Par ailleurs, la propriété name permet d’afficher le nom de la caméra active. Remarque : si vous diffusez en continu la vidéo émanant d’une caméra via le réseau, vous devez toujours traiter les interruptions du réseau. Ces interruptions se produisent pour diverses raisons, en particulier sur les périphériques mobiles.
Utilisation de caméras
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La connexion à une caméra peut nécessiter moins de code que l’utilisation des classes NetConnection et NetStream pour charger un fichier vidéo. Par contre, l’utilisation de la classe Camera peut parfois s’avérer délicate, car avec Flash Player, il est nécessaire d’avoir l’autorisation de l’utilisateur pour se connecter à sa caméra et la rendre accessible par code. Le code suivant montre comment utiliser la classe Camera pour établir une connexion avec la caméra de l’utilisateur : var cam:Camera = Camera.getCamera(); var vid:Video = new Video(); vid.attachCamera(cam); addChild(vid);
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lors de la programmation d’une application destinée à gérer la caméra de l’utilisateur, prenez les précautions suivantes :
élégamment la réponse.
• Elle n’est pas prise en charge par les applications AIR mobiles qui font appel au mode de rendu par processeur graphique.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour établir une connexion avec la caméra de l’utilisateur, la première étape consiste à créer une occurrence de l’objet Camera, en créant une variable du type Camera et en l’initialisant avec la valeur renvoyée par la méthode statique Camera.getCamera(). L’étape suivante consiste à créer un objet Video et à lui affecter l’objet Camera. La troisième étape consiste à ajouter cet objet Video à la liste d’affichage. Les étapes 2 et 3 sont nécessaires, car la classe Camera n’étend pas la classe DisplayObject, il est donc impossible de l’ajouter directement à la liste d’affichage. Pour afficher le signal vidéo provenant de la caméra, vous devez ensuite créer un autre objet Video et appeler la méthode attachCamera(). Le code suivant illustre ces trois opérations : var cam:Camera = Camera.getCamera(); var vid:Video = new Video(); vid.attachCamera(cam); addChild(vid);
Pour une application réelle, d’autres tâches sont nécessaires. Pour plus d’informations, voir « Vérification de la présence de caméras » à la page 539 et « Détection de l’autorisation d’accéder à la caméra » à la page 540.
Lee Brimelow : How to access the camera on Android devices (disponible en anglais uniquement)
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Avant de tenter d’utiliser les méthodes ou propriétés d’une occurrence de Camera, il est préférable de vérifier qu’une caméra est bien installée. Il existe deux techniques pour vérifier la présence d’une ou plusieurs caméras :
{ trace("User has at least one camera installed."); var cam:Camera = Camera.getCamera(); // Get default camera. } else Dans les applications AIR des périphériques mobiles, vous pouvez accéder à la ou aux caméras dont dispose le périphérique. Sur les périphériques mobiles, vous pouvez utiliser soit la caméra frontale soit la caméra arrière, mais pas les deux en même temps. (Si vous activez une deuxième caméra, la première est tout d’abord désactivée.) La caméra frontale est mise en miroir horizontalement sur iOS ; elle ne l’est pas sur Android.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Dans le sandbox de l’application AIR, l’application peut accéder à n’importe quelle caméra sans autorisation de l’utilisateur. Sur Android, l’application doit toutefois spécifier l’autorisation CAMERA d’Android dans le descripteur d’application. Avant que Flash Player ne puisse afficher les résultats d’une caméra, l’utilisateur doit autoriser Flash Player à accéder à la caméra de façon explicite. Lorsque la méthode attachCamera() est appelée, la boîte de dialogue Paramètres de Flash Player est affichée pour permettre à l’utilisateur d’autoriser ou refuser à Flash Player l’accès à la caméra et au microphone. Si l’utilisateur a accordé son autorisation, Flash Player affiche les résultats de la caméra dans l’occurrence de l’objet Video sur la scène. Si l’utilisateur a refusé, Flash Player ne peut pas se connecter à la caméra et l’objet Video n’affiche rien.
Optimisation de la qualité des vidéos de la caméra Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Par défaut, les nouvelles occurrences de la classe Video ont une largeur de 320 pixels sur une hauteur de 240 pixels. Pour optimiser la qualité vidéo, veillez à donner à vos objets Video les mêmes dimensions que celles de l’objet Camera. Pour obtenir la largeur et la hauteur de l’objet Camera, utilisez les propriétés width et height de la classe Camera. Vous pouvez alors adapter les propriétés width et height de l’objet Video à ces dimensions, ou transmettre celles-ci à la méthode constructeur de la classe Video, comme dans le fragment de code ci-dessous : var cam:Camera = Camera.getCamera(); if (cam != null) { var vid:Video = new Video(cam.width, cam.height); vid.attachCamera(cam); addChild(vid); }
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe Camera contient plusieurs propriétés qui permettent de suivre l’état de l’objet Camera. Par exemple, le code ci-dessous affiche plusieurs propriétés de la caméra à l’aide d’un objet Timer et d’une occurrence de champ de texte dans la liste d’affichage :
Adobe® Access™ est une solution de protection du contenu. Elle permet aux propriétaires, aux distributeurs et aux publicitaires d’exploiter de nouvelles sources de revenus en assurant un accès transparent à un contenu Premium. Les éditeurs utilisent Adobe Access pour chiffrer du contenu, créer des stratégies et délivrer des licences. Adobe Flash Player et Adobe AIR intègrent une bibliothèque DRM, le module Adobe Access. Ce module permet au moteur d’exécution de communiquer avec le serveur de licences Adobe Access et de lire le contenu protégé. Le moteur d’exécution complète ainsi le cycle de vie du contenu protégé par Adobe Access et distribué par Flash Media Server. Grâce à Adobe Access, les fournisseurs de contenu sont en mesure de proposer des contenus libres de droits et des contenus Premium. Imaginons qu’un consommateur souhaite visionner une émission de télévision sans coupure publicitaire. Il s’enregistre et s’acquitte d’un droit auprès de l’éditeur de contenu. Il peut ensuite entrer ses informations d’identification pour accéder au site et visionner l’émission sans publicité. Prenons à présent l’exemple d’un consommateur qui souhaite visionner un contenu hors connexion lorsqu’il est en déplacement et ne dispose pas d’un accès à Internet. Ce flux de travail hors connexion est pris en charge par les applications AIR. Après s’être enregistré et acquitté des droits relatifs au contenu auprès de l’éditeur, l’utilisateur peut accéder au contenu et à l’application AIR associée et les télécharger à partir du site Web de l’éditeur. Par le biais de l’application AIR, l’utilisateur peut visionner le contenu hors connexion pendant la période autorisée. Il est également possible de partager le contenu avec d’autres périphériques dans le même groupe de périphériques à l’aide de domaines (nouveauté dans la version 3.0). Adobe prend également en charge l’accès anonyme, qui ne nécessite pas d’authentification. Par exemple, un éditeur peut avoir recours à un accès anonyme pour distribuer du contenu publicitaire. Un accès anonyme permet en outre à un éditeur d’accéder gratuitement au contenu actuel pendant une période spécifique. Le fournisseur de contenu peut également stipuler et limiter le type et la version du lecteur requis pour le visionnement du contenu. Lorsqu’un utilisateur tente de lire un contenu protégé dans Flash Player ou Adobe AIR, l’application doit appeler les API DRM. Les API DRM démarrent le flux de travail requis par la lecture du contenu protégé. Via le module Adobe Access, le moteur d’exécution contacte le serveur de licences. Le serveur de licences authentifie l’utilisateur, le cas échéant, et délivre une licence qui autorise la lecture du contenu protégé. Le moteur d’exécution reçoit la licence et déchiffre le contenu pour qu’il puisse être lu. La procédure permettant à l’application de lire un contenu protégé par Adobe Access est décrite ci-après. Il est inutile de maîtriser le chiffrement de contenu ou la gestion des régulations par le biais d’Adobe Access. Nous partons toutefois du principe que vous communiquez avec le serveur de licences Adobe Access pour authentifier l’utilisateur et récupérer la licence. Nous considérons également comme acquis que vous créez une application réservée à la lecture de contenu protégé par Adobe Access. Pour accéder à une présentation d’Adobe Access, notamment la création de régulations, voir la documentation livrée avec le produit.
Utilisation de la gestion des droits d’auteur numériques (DRM)
Flash Player 10.1 et les versions ultérieures, Adobe AIR 2.0 et les versions ultérieures Important : Flash Player 11.5 et les versions ultérieures intègrent le module Adobe Access ; l’étape de mise à jour (l’appel de SystemUpdater.update(SystemUpdaterType.DRM)) est donc inutile. Les navigateurs et plates-formes suivants sont concernés :
8 sur les processeurs Intel
• Adobe AIR (version de bureau et version mobile) L’étape de mise à jour est toujours requise dans les cas suivants :
• Flash Player 11.4 et versions antérieures, à l’exception de Google Chrome 22 et des versions ultérieures (toutes les plates-formes) ou de Google Chrome 21 et des versions ultérieures (Windows) Remarque : vous pouvez toujours appeler SystemUpdater.update(SystemUpdaterType.DRM) sur un système doté de Flash Player 11.5 ou d’une version ultérieure, mais rien n’est téléchargé. Le flux de travail de haut niveau suivant indique comment une application peut récupérer et lire du contenu protégé. Il part du principe que l’application est conçue spécifiquement pour lire un contenu protégé par Adobe Access : 1 Récupérez les métadonnées du contenu. 2 Exécutez les mises à jour de Flash Player, s’il y a lieu. 3 Vérifiez si une licence est disponible localement. Si tel est le cas, chargez-la et passez à l’étape 7. Dans le cas
4 Vérifiez si l’authentification est obligatoire. Dans le cas contraire, passez à l’étape 7. 5 Si l’authentification est obligatoire, demandez les informations d’identification à l’utilisateur et transmettez-les au
6 Si l’enregistrement de domaine est requis, joignez le domaine (AIR 3.0 et versions ultérieures). 7 Lorsque l’authentification aboutit, téléchargez la licence du serveur. 8 Lisez le contenu.
Si l’utilisateur est autorisé à accéder au contenu hors connexion, le voucher est mis en mémoire cache et le contenu chiffré est téléchargé sur la machine de l’utilisateur. L’utilisateur peut accéder au contenu pendant le nombre de jours défini dans la durée de mise en mémoire cache de la licence. La propriété detail de l’événement contient "DRM.voucherObtained". L’application décide de l’emplacement local de stockage du contenu pour assurer sa disponibilité hors connexion. Vous pouvez également précharger les vouchers à l’aide de la classe DRMManager. Remarque : la mise en mémoire cache et le préchargement de vouchers sont pris en charge dans AIR et dans Flash Player. Néanmoins, le téléchargement et le stockage du contenu chiffré sont pris en charge uniquement dans AIR. C’est l’application elle-même qui est chargée de gérer explicitement les événements d’erreur, notamment lorsque l’utilisateur saisit correctement ses informations d’identification, mais que le voucher qui protège le contenu chiffré limite l’accès au contenu. Un utilisateur authentifié ne peut par exemple pas accéder au contenu s’il ne s’est pas acquitté des droits. Ce cas peut également se produire lorsque deux membres inscrits du même éditeur tentent de partager du contenu que seul l’un d’entre eux a payé. L’application doit informer l’utilisateur de l’erreur et proposer une solution de remplacement. Par exemple, l’application peut donner à l’utilisateur des instructions sur le mode d’inscription et de paiement des droits d’affichage.
Ce flux de travail illustre de manière plus détaillée le flux de travail associé à un contenu protégé. Il décrit les API impliquées dans la lecture du contenu protégé par Adobe Access. 1 Par le biais d’un objet URLLoader, chargez les octets du fichier de métadonnées du contenu protégé. Définissez cet
Tout contenu contrôlé par Adobe Access contient des métadonnées Adobe Access. Lorsque le contenu est mis en package, ces métadonnées peuvent être enregistrées dans un fichier de métadonnées distinct (.metadata) parallèlement au contenu. Pour plus d’informations, voir la documentation d’Adobe Access. 2 Créez une occurrence de DRMContentData. Placez ce code dans un bloc try-catch : new DRMContentData(metadata_bytes)
3 (Flash Player uniquement) Le moteur d’exécution recherche le module Adobe Access. S’il ne le trouve pas, une
Pour gérer cette erreur, téléchargez le module Adobe Access à l’aide de l’API SystemUpdater. Une fois ce module téléchargé, l’objet SystemUpdater distribue un événement COMPLETE. Définissez un écouteur d’événement qui retourne à l’étape 2 lors de la distribution de cet événement. Le code suivant illustre ces étapes : flash.system.SystemUpdater.addEventListener(Event.COMPLETE, updateCompleteHandler); flash.system.SystemUpdater.update(flash.system.SystemUpdaterType.DRM)
4 Créez des écouteurs qui écoutent les événements DRMStatusEvent et DRMErrorEvent distribués par l’objet
DRMManager.addEventListener(DRMStatusEvent.DRM_STATUS, onDRMStatus); Essayez tout d’abord de charger une licence stockée localement pour lire le contenu : DRMManager.loadvoucher(drmContentData, LoadVoucherSetting.LOCAL_ONLY)
6 Si l’objet DRMVoucher possède une valeur autre que null, le voucher est valide. Passez à l’étape 13. 7 Si l’objet DRMVoucher est défini sur null, vérifiez la méthode d’authentification requise par la régulation associée
8 Si la méthode d’authentification est ANONYMOUS, passez à l’étape 13. 9 Si la méthode d’authentification est USERNAME_AND_PASSWORD, l’application doit intégrer un mécanisme
DRMManager.authenticate(metadata.serverURL, metadata.domain, username, password)
événement DRMAuthenticationCompleteEvent si elle aboutit. Associez des écouteurs à ces événements. 10 Si la méthode d’authentification est UNKNOWN, une méthode d’authentification personnalisée doit être utilisée. Dans
API ActionScript 3.0. La procédure d’authentification personnalisée doit produire un jeton d’authentification qu’il est possible de transmettre à la méthode DRMManager.setAuthenticationToken(). 11 Si l’authentification échoue, l’application doit retourner à l’étape 9. Assurez-vous que l’application intègre un
12 Pour utiliser le jeton stocké au lieu d’inviter l’utilisateur à entrer des informations d’identification, définissez-le à
d’octets placé en mémoire cache. Récupérez ce jeton à l’aide de la propriété DRMAuthenticationCompleteEvent.token. Vous pouvez stocker et utiliser le jeton d’authentification pour éviter à l’utilisateur d’avoir à entrer plusieurs fois les informations d’identification associées au contenu. Le serveur de licences détermine la période de validité du jeton d’authentification. 14 Si l’authentification aboutit, téléchargez la licence du serveur de licences : DRMManager.loadvoucher(drmContentData, LoadVoucherSetting.FORCE_REFRESH)
Ecoutez cet événement. Une fois ce dernier distribué, vous pouvez lire le contenu. 15 Lisez la vidéo en créant un objet NetStream, puis en appelant sa méthode play() : stream = new NetStream(connection); stream.addEventListener(DRMStatusEvent.DRM _STATUS, drmStatusHandler); stream.addEventListener(DRMErrorEvent.DRM_ERROR, drmErrorHandler); stream.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler); stream.client = new CustomClient(); video.attachNetStream(stream); stream.play(videoURL);
Lors de la création d’un objet DRMContentData, celui-ci est utilisé en tant qu’objet session qui fait référence au module DRM de Flash Player. Toutes les API DRMManager qui reçoivent cet objet DRMContentData utilisent ce module DRM particulier. Il existe néanmoins deux API DRMManager qui n’utilisent pas l’objet DRMContentData. Voici ces règles : 1 authenticate() 2 setAuthenticationToken()
1 L’application crée un objet DRMContentDatacontentData1, qui utilise AdobeCP1 comme module DRM. 2 L’application invoque la méthode DRMManager.authenticate(contentData1.serverURL,...). 3 L’application invoque la méthode DRMManager.loadVoucher(contentData1, ...).
DRMManager.authenticate() finit par effectuer l’authentification à l’aide du module DRM AdobeCP2. La méthode loadVoucher() de l’étape 3 échoue, car elle utilise toujours le module DRM AdobeCP1. Il est possible que la mise à jour ait eu lieu suite à l’invocation de la mise à jour du module DRM par une autre application. Vous pouvez éviter ce scénario en invoquant la mise à jour du module DRM au démarrage de l’application.
Dernière mise à jour le 27/4/2013
Utilisation de la gestion des droits d’auteur numériques (DRM)
• DRMStatusEvent, distribué par NetStream et DRMManager • StatusEvent • NetStatusEvent (voir « Ecoute d’un événement de mise à jour » à la page 562) Pour prendre en charge un contenu protégé par Adobe Access, associez des écouteurs aux événements DRM.
Adobe AIR 1.5 et les versions ultérieures Vous pouvez précharger les vouchers (licences) requis pour lire le contenu protégé par Adobe Access. Les vouchers préchargés permettent aux utilisateurs de visionner le contenu même si leur connexion Internet n’est pas active. (Le processus de préchargement à proprement parler requiert une connexion à Internet.) Faites appel à la méthode preloadEmbeddedMetadata() de la classe NetStream et à la classe DRMManager pour précharger les vouchers. Dans AIR 2.0 et les versions ultérieures, vous pouvez précharger directement des vouchers par le biais d’un objet DRMContentData. Il est préférable d’utiliser cette technique, car elle permet de mettre à jour l’objet DRMContentData indépendamment du contenu. (La méthode preloadEmbeddedData() extrait l’objet DRMContentData du contenu.)
Adobe AIR 2.0 et les versions ultérieures La procédure ci-dessous décrit le préchargement du voucher associé à un fichier multimédia protégé par le biais d’un objet DRMContentData. 1 Extrayez les métadonnées binaires associées au contenu mis en package. Si vous utilisez Adobe Access Java
2 Créez un objet DRMContentData en transmettant les métadonnées à la fonction constructeur : var drmData:DRMContentData = new DRMContentData( metadata );
Adobe AIR 1.5 et les versions ultérieures La procédure suivante décrit le préchargement du voucher associé à un fichier multimédia protégé par DRM par le biais de preloadEmbeddedMetadata() : 1 Téléchargez et stockez le fichier multimédia. (Il est uniquement possible de précharger les métadonnées du module
2 Créez les objets NetConnection et NetStream, en fournissant des implémentations pour les fonctions de rappel onDRMContentData() et onPlayStatus() de l’objet client NetStream.
4 Appelez la méthode NetStream preloadEmbeddedMetadata(), en transmettant l’objet NetStreamPlayOptions
Si la valeur de la propriété authenticationMethod de l’objet DRMContentData est flash.net.drm.AuthenticationMethod.USERNAME_AND_PASSWORD, authentifiez l’utilisateur sur le serveur de
7 La fonction de rappel onPlayStatus() est invoquée lorsque l’analyse du fichier est terminée. Si la fonction onDRMContentData() n’a pas été appelée, le fichier ne contient pas les métadonnées nécessaires à l’obtention d’un
L’exemple de code pour AIR suivant illustre le préchargement d’un voucher associé à un fichier multimédia local : package { import flash.display.Sprite; import flash.events.DRMAuthenticationCompleteEvent; import flash.events.DRMAuthenticationErrorEvent; import flash.events.DRMErrorEvent; import flash.ev ents.DRMStatusEvent; import flash.events.NetStatusEvent; import flash.net.NetConnection; import flash.net.NetStream; import flash.net.NetStreamPlayOptions; import flash.net.drm.AuthenticationMethod; import flash.net.drm.DRMContentData; import flash.net.drm.DRMManager; import flash.net.drm.LoadVoucherSetting; public class DRMPreloader extends Sprite { private var videoURL:String = "app-storage:/video.flv"; private var userName:String = "user"; private var password:String = "password"; private var preloadConnection:NetConnection; private var preloadStream:NetStream; private var drmManager:DRMManager = DRMManager.getDRMManager(); private var drmContentData:DRMContentData; public function DRMPreloader():void { drmManager.addEventListener( DRMAuthenticationCompleteEvent.AUTHENTICATION_COMPLETE, onAuthenticationComplete); drmManager.addEventListener(DRMAuthenticationErrorEvent.AUTHENTICATION_ERROR, onAuthenticationError); drmManager.addEventListener(DRMStatusEvent.DRM_STATUS, onDRMStatus); drmManager.addEventListener(DRMErrorEvent.DRM_ERROR, onDRMError); preloadConnection = new NetConnection(); preloadConnection.addEventListener(NetStatusEvent.NET_STATUS, onConnect); preloadConnection.connect(null); Flash Player 10.1 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe NetStream propose une connexion en flux continu unidirectionnelle entre Flash Player ou une application AIR et Flash Media Server ou le système de fichiers local. (La classe NetStream gère également les téléchargements en mode progressif.) Un objet NetStream est un canal dans un objet NetConnection. La classe NetStream distribue quatre événements DRM : Evénement
Dans le code suivant pour AIR, le nom d’utilisateur (« administrator »), le mot de passe (« password ») et le type d’authentification (« drm ») sont définis pour authentifier l’utilisateur. La méthode setDRMAuthenticationCredentials() doit fournir des informations d’identification connues et acceptées par le fournisseur de contenu. Ces informations d’identification sont identiques aux données saisies par l’utilisateur pour visionner le contenu. Ce chapitre ne contient pas le code permettant de lire la vidéo et de s’assurer qu’une connexion au flux vidéo a abouti. var connection:NetConnection = new NetConnection(); connection.connect(null); var videoStream:NetStream = new NetStream(connection); videoStream.addEventListener(DRMAuthenticateEvent.DRM_AUTHENTICATE, drmAuthenticateEventHandler) private function drmAuthenticateEventHandler(event:DRMAuthenticateEvent):void { videoStream.setDRMAuthenticationCredentials("administrator", "password", "drm"); }
Flash Player 10.1, Adobe AIR 1.0 et les versions ultérieures Un objet NetStream distribue un objet DRMStatusEvent lorsque la lecture du contenu protégé par Adobe Access débute. (Pour cela, la licence doit être vérifiée, et l’utilisateur doit être authentifié et autorisé à afficher le contenu). L’objet DRMStatusEvent est également distribué lorsqu’un utilisateur anonyme est autorisé à accéder au contenu. La licence est vérifiée pour s’assurer que les utilisateurs anonymes, qui ne requièrent pas d’authentification, sont autorisés à lire le contenu. Les utilisateurs anonymes risquent de ne pas être autorisés à accéder au contenu pour diverses raisons. Un utilisateur anonyme ne peut, par exemple, pas accéder au contenu lorsque la licence est arrivée à expiration. L’objet DRMStatusEvent contient des informations relatives à la licence. Il mémorise par exemple des informations relatives à la disponibilité hors connexion de la licence ou à la date d’expiration du voucher (au terme de laquelle il est impossible de visionner le contenu). L’application peut utiliser ces données pour communiquer l’état des régulations de l’utilisateur et les autorisations correspondantes.
Adobe AIR 1.0 et les versions ultérieures L’objet DRMAuthenticateEvent est distribué lorsqu’un objet NetStream essaie de lire un contenu protégé qui requiert la saisie des informations d’identification de l’utilisateur avant la lecture. Le gestionnaire DRMAuthenticateEvent est chargé de collecter les informations d’identification requises (nom d’utilisateur, mot de passe et type) et de les transmettre à la méthode NetStream.setDRMAuthenticationCredentials() pour qu’elles soient validées. Chaque application AIR doit intégrer un mécanisme de collecte des informations d’identification des utilisateurs. L’application pourrait par exemple proposer à l’utilisateur une interface simple permettant de saisir son nom d’utilisateur et son mot de passe. Veillez également à intégrer un mécanisme de gestion et de restriction des tentatives d’authentification successives.
Adobe AIR 1.0 et les versions ultérieures La classe DRMAuthenticateEvent comprend les propriétés suivantes : Propriété
Le code suivant est un exemple Flex d’interface utilisateur simple permettant de collecter les informations d’identification des utilisateurs. Il se compose d’un objet Panel contenant deux objets TextInput (le premier étant réservé aux noms d’utilisateur et le second aux mots de passe). L’objet Panel comporte également un bouton permettant de démarrer la méthode credentials(). <mx:Panel x="236.5" y="113" width="325" height="204" layout="absolute" title="Login"> <mx:TextInput x="110" y="46" id="uName"/> <mx:TextInput x="110" y="76" id="pWord" displayAsPassword="true"/> état provient de l’état de base lorsque l’objet DRMAuthenticateEvent est envoyé. L’exemple suivant contient un objet VideoDisplay doté d’un attribut source qui pointe vers un fichier FLV protégé. Dans ce cas, la méthode credentials() est modifiée de façon à ce qu’elle renvoie également l’application à son état de base. Pour cela, les informations d’identification de l’utilisateur doivent être transmises et les valeurs de l’objet TextInput réinitialisées. <?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" width="800" height="500" title="DRM FLV Player" creationComplete="initApp()" > <mx:states> Même si les informations d’identification de l’utilisateur sont valides, il est possible que les conditions du voucher l’empêchent d’afficher un contenu chiffré. Par exemple, un utilisateur peut se voir refuser l’accès à un contenu s’il tente de lire ce contenu dans une application non autorisée. Une application non autorisée est une application que l’éditeur du contenu chiffré n’a pas validée. Dans ce cas, un objet DRMErrorEvent est distribué. Des événements d’erreur peuvent également être déclenchés si le contenu est endommagé ou si la version de l’application ne correspond pas aux spécifications du voucher. L’application doit intégrer un mécanisme de gestion des erreurs approprié.
Flash Player 10.1 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour obtenir la liste complète des erreurs, voir Erreurs d’exécution dans le Guide de référence d’ActionScript 3.0 pour Flash Professional. Les erreurs DRM débutent au numéro 3300.
La classe DRMManager permet de gérer les vouchers et les sessions du serveur des droits multimédias dans les applications. Gestion des vouchers (AIR uniquement) Lorsqu’un utilisateur lit un contenu protégé, le moteur d’exécution obtient et place en mémoire cache la licence requise pour visionner le contenu. Si l’application enregistre le fichier localement et si la licence autorise la lecture hors connexion, l’utilisateur peut visionner le contenu dans l’application AIR. La lecture locale hors connexion est possible même si la connexion au serveur de droits multimédias n’est pas disponible. Vous pouvez pré-placer en mémoire cache le voucher par le biais de DRMManager et de la méthode preloadEmbeddedMetadata() de NetStream. Il est inutile que l’application obtienne la licence nécessaire au visionnement du contenu. Par exemple, votre application peut télécharger le fichier multimédia, puis obtenir le voucher pendant que l’utilisateur est encore en ligne. Pour précharger un voucher, utilisez la méthode NetStream preloadEmbeddedMetadata() pour obtenir un objet DRMContentData. L’objet DRMContentData contient l’URL et le domaine du serveur de gestion des droits d’auteur pouvant fournir la licence et indique si l’authentification de l’utilisateur est requise. Avec ces informations, vous pouvez appeler la méthode DRMManager loadVoucher() pour obtenir le voucher et le mettre en cache. La procédure de préchargement des vouchers est décrite plus en détails à la section « Préchargement de vouchers pour une lecture hors connexion » à la page 550. Gestion des sessions Vous pouvez également utiliser DRMManager pour authentifier l’utilisateur auprès d’un serveur de gestion des droits d’auteur et pour gérer les sessions persistantes. Appelez la méthode DRMManager authenticate() pour établir une session auprès du serveur de gestion des droits d’auteur. Une fois l’authentification réussie, le DRMManager distribue un objet DRMAuthenticationCompleteEvent qui contient un jeton de session. Vous pouvez enregistrer ce jeton pour établir les sessions futures de sorte que l’utilisateur n’ait plus besoin de fournir les informations d’identification de son compte. Transmettez le jeton à la méthode setAuthenticationToken() pour établir une nouvelle session authentifiée. (Les paramètres du serveur générés par le jeton déterminent la date d’expiration du jeton et d’autres attributs. Le code de l’application AIR ne doit pas interpréter la structure de données du jeton, car cette structure est susceptible de changer lors de futures mises à jour d’AIR.)
« DRM.voucherObtained » et la propriété voucher contient l’objet DRMVoucher. Si le voucher n’a pas été obtenu, la propriété detail (AIR uniquement) conserve la valeur : « DRM.voucherObtained », mais la propriété voucher est null. Il est impossible d’obtenir un voucher si, par exemple, vous définissez LoadVoucherSetting sur localOnly et qu’aucun voucher n’a été placé dans la mémoire cache locale. Si l’appel de la méthode loadVoucher() échoue, en raison d’une erreur de communication ou d’authentification, par exemple, le DRMManager distribue alors un objet DRMErrorEvent ou DRMAuthenticationErrorEvent.
Flash Player 10.1 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures Le DRMManager distribue un objet DRMAuthenticationCompleteEvent lorsque l’utilisateur est bien authentifié via un appel à la méthode authenticate(). L’objet DRMAuthenticationCompleteEvent contient un jeton réutilisable qui peut servir à maintenir l’authentification de l’utilisateur dans plusieurs sessions de l’application. Transmettez ce jeton à la méthode setAuthenticationToken() du DRMManager pour rétablir la session. (Le créateur du jeton définit les attributs du jeton, notamment sa date d’expiration. Adobe ne fournit pas d’API capable d’examiner les attributs du jeton.)
Flash Player 10.1 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures Le DRMManager distribue un objet DRMAuthenticationErrorEvent lorsqu’un utilisateur n’a pas pu s’authentifier via un appel aux méthodes authenticate() ou setAuthenticationToken().
Flash Player 10.1 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures L’objet DRMContentData contient les propriétés de métadonnées du contenu protégé par Adobe Access. Les propriétés DRMContentData contiennent les informations nécessaires à l’obtention du voucher de licence permettant d’afficher le contenu. La classe DRMContentData permet d’obtenir le fichier de métadonnées associé au contenu, comme indiqué à la section « Flux de travail détaillé des API » à la page 547. Pour plus d’informations, voir la classe DRMContentData dans le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash.
Flash Player 10.1 et les versions ultérieures Important : Flash Player 11.5 et les versions ultérieures intègrent le module Adobe Access ; l’étape de mise à jour (l’appel de SystemUpdater.update(SystemUpdaterType.DRM)) est donc inutile. Les navigateurs et plates-formes suivants sont concernés :
• Plug-in Flash Player 11.5, pour tous les navigateurs • Adobe AIR (version de bureau et version mobile) L’étape de mise à jour est toujours requise dans les cas suivants :
• Flash Player 11.4 et versions antérieures, à l’exception de Google Chrome 22 et des versions ultérieures (toutes les plates-formes) ou de Google Chrome 21 et des versions ultérieures (Windows) Remarque : vous pouvez toujours appeler SystemUpdater.update(SystemUpdaterType.DRM) sur un système doté de Flash Player 11.5 ou d’une version ultérieure, mais rien n’est téléchargé. Flash Player doit disposer du module Adobe Access pour prendre en charge ses fonctions. Lorsque Flash Player tente de lire un contenu protégé, le moteur d’exécution indique si le module ou une nouvelle version de Flash Player doit être téléchargé. Flash Player permet ainsi aux développeurs SWF de ne pas faire de mise à jour, le cas échéant. En règle générale, pour lire du contenu protégé, les développeurs SWF mettent à jour le module ou le lecteur Adobe Access requis. Pour effectuer la mise à jour, vous disposez de l’API SystemUpdater, qui permet d’obtenir la version la plus récente du module Adobe Access ou de Flash Player. L’API SystemUpdater n’autorise qu’une mise à jour à la fois. Le code d’erreur 2202 indique qu’une mise à jour est en cours d’exécution dans l’occurrence active du moteur d’exécution ou une autre occurrence. Ainsi, s’il se produit une mise à jour d’une occurrence de Flash Player dans Internet Explorer, il est impossible d’effectuer une mise à jour d’une occurrence de Flash Player dans Firefox. Seules les plates-formes de bureau prennent en charge l’API SystemUpdater. Remarque : pour les versions de Flash Player antérieures à 10.1, utilisez le mécanisme de mise à jour pris en charge par les versions antérieures du lecteur (téléchargement et installation manuels à partir du site www.adobe.com ou d’ExpressInstall). Le programme d’installation d’AIR gère par ailleurs les mises à jour requises d’Adobe Access, mais non l’API SystemUpdater.
Flash Player 10.1 et les versions ultérieures Lorsqu’une mise à jour du module Adobe Access est nécessaire, l’objet NetStream distribue un événement NetStatusEvent dont la valeur de code correspond à DRM.UpdateNeeded. Cette valeur indique que l’objet NetStream ne peut pas lire le flux protégé par le biais de tout module Adobe Access actuellement installé. Ecoutez cet événement et appelez le code suivant : SystemUpdater.update(flash.system.SystemUpdaterType.DRM)
à la page 547. Remarque : si play() est appelé sur un flux chiffré dans des lecteurs antérieurs à 10.1, un événement NetStatusEvent dont la valeur de code correspond à NetStream.Play.StreamNotFound est distribué. Pour les lecteurs antérieurs, faites appel au mécanisme de mise à jour pris en charge (téléchargement et installation manuels à partir du site www.adobe.com ou d’ExpressInstall). S’il est nécessaire de mettre à jour le lecteur en tant que tel, l’objet SystemUpdater distribue un événement StatusEvent dont la valeur de code correspond à DRM.UpdateNeededButIncompatible. Pour mettre à jour le lecteur, l’accord de l’utilisateur est obligatoire. Intégrez à l’application une interface permettant à l’utilisateur d’accepter et de démarrer la mise à jour du lecteur. Ecoutez l’événement StatusEvent et appelez le code suivant : SystemUpdater.update(flash.system.SystemUpdaterType.SYSTEM);
D’autres événements associés à la classe SystemUpdater sont passés en revue dans le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash. Une fois la mise à jour du lecteur terminée, l’utilisateur est renvoyé à la page initiale. Le module Adobe Access est téléchargé et la lecture du flux peut démarrer.
Flash Player 11 et les versions ultérieures, Adobe AIR 3.0 et les versions ultérieures Il est possible d’obtenir les licences hors bande (c’est-à-dire sans se connecter au serveur de licences Adobe Access) en enregistrant le voucher (la licence) sur le disque et dans la mémoire à l’aide de la méthode storeVoucher. Pour lire une vidéo chiffrée dans Flash Player et AIR, le moteur d’exécution respectif doit obtenir le voucher DRM correspondant à cette vidéo. Le voucher DRM contient la clé de chiffrement de la vidéo et est généré par le serveur de licences Adobe Access que le client a déployé. Le moteur d’exécution de Flash Player/AIR obtient généralement ce voucher en envoyant une demande de voucher au serveur de licences Adobe Access indiqué dans les métadonnées DRM de la vidéo (classe DRMContentData). L’application Flash/AIR peut déclencher cette demande de licence en appelant la méthode DRMManager.loadVoucher(). Le moteur d’exécution de Flash Player ou d’AIR peut par ailleurs solliciter automatiquement une licence au début de la lecture de la vidéo chiffrée si aucune licence ne correspond au contenu sur le disque ou dans la mémoire. Dans tous les cas, la communication avec le serveur de licences Adobe Access a une incidence sur les performances de l’application Flash/AIR. DRMManager.storeVoucher() permet à l’application Flash/AIR d’envoyer les vouchers DRM obtenus hors bande au moteur d’exécution de Flash Player ou d’AIR. Le moteur d’exécution peut alors ignorer le processus de demande de licence et utiliser les vouchers transmis pour lire les vidéos chiffrées. Il est toujours nécessaire de générer le voucher DRM via le serveur de licences Adobe Access avant de pouvoir l’obtenir hors bande. Vous avez néanmoins la possibilité d’héberger les vouchers sur un serveur HTTP plutôt que sur un serveur de licences Adobe Access public.
DRMVoucher.toByteArray(), et il est possible d’importer les vouchers sur les autres machines à l’aide de la méthode DRMManager.storeVoucher().
Les vouchers DRM sont liés à la machine de l’utilisateur final. Par conséquent, les applications Flash/AIR nécessitent un ID unique pour que la machine de l’utilisateur puisse faire référence à l’objet de voucher DRM sérialisé approprié. Le scénario suivant décrit la procédure d’enregistrement d’un périphérique : Vous devez au préalable effectuer les tâches suivantes :
• Configurez un serveur HTTP en vue d’obtenir des licences pré-générées. • Créez une application Flash afin d’accéder au contenu protégé. La phase d’enregistrement du périphérique implique les actions suivantes : 1 L’application Flash crée un ID généré de façon aléatoire. 2 L’application Flash invoque la méthode DRMManager.authenticate(). L’application doit inclure l’ID généré de
3 L’action mentionnée à l’étape 2 pousse Adobe Access à envoyer une demande d’authentification au serveur du
4 Le serveur répond à la demande via un message « success ». 5 L’application Flash enregistre l’ID généré localement dans un objet partagé local (LSO).
1 L’application Flash tente de localiser l’ID généré dans l’objet LSO. 2 Si l’ID généré est détecté, l’application Flash l’utilise lors du téléchargement des licences pré-générées. L’application
3 Si l’ID généré est introuvable, l’application Flash suit la procédure d’enregistrement de périphérique.
Lorsque l’utilisateur du périphérique invoque l’option de rétablissement des paramètres par défaut, le certificat du périphérique est supprimé. Pour poursuivre la lecture du contenu protégé, l’application Flash doit répéter la procédure d’enregistrement de périphérique. Si l’application Flash envoie une licence pré-chargée obsolète, le client Adobe Access la refuse, car la licence a été chiffrée pour un ancien ID de périphérique.
Flash Player 11 et les versions ultérieures, Adobe AIR 3.0 et les versions ultérieures Si les métadonnées du contenu indiquent que l’enregistrement du domaine est requis, l’application AIR peut invoquer une API en vue de se joindre à un groupe de périphériques. Cette action déclenche une demande d’enregistrement à envoyer au serveur de domaine. Dès qu’une licence est délivrée à un groupe de périphériques, il est impossible de l’exporter et de la partager avec d’autres périphériques ayant rejoint le groupe. Les informations concernant le groupe de périphériques sont alors utilisées dans l’objet VoucherAccessInfo du DRMContentData afin de présenter les informations requises pour récupérer et consommer un voucher.
Pour lire du contenu chiffré avec Adobe Access, procédez comme suit : 1 A l’aide de VoucherAccessInfo.deviceGroup, vérifiez si l’enregistrement du groupe de périphériques est requis. 2 Si l’authentification est requise : a Utilisez la propriété DeviceGroupInfo.authenticationMethod pour savoir si l’authentification est requise. b Si l’authentification est requise, authentifiez l’utilisateur en appliquant l’UNE des procédures suivantes :
DRMManager.authenticate(deviceGroup.serverURL, deviceGroup.domain, nom d'utilisateur, mot de passe).
DRMManager.setAuthenticationToken(). Pour exporter la licence correspondant au contenu, n’importe quel périphérique peut fournir les octets bruts de la licence à l’aide de la méthode DRMVoucher.toByteArray() une fois la licence obtenue auprès du serveur de licences Adobe Access. Le fournisseur de contenu limite généralement le nombre de périphériques dans un groupe de périphériques. Si vous atteignez cette limite, il est possible que vous deviez appeler la méthode DRMManager.removeFromDeviceGroup() sur un périphérique non utilisé avant d’enregistrer le périphérique actuel.
L’application Flash peut envoyer une demande d’aperçu de licence, c’est-à-dire qu’elle peut lancer une opération d’aperçu avant de prier l’utilisateur d’acheter le contenu en vue de déterminer si la machine de ce dernier répond aux critères de lecture requis. L’aperçu de licence signifie que le client est en mesure d’afficher un aperçu de la licence (pour connaître les droits octroyés par la licence), mais qu’il ne peut pas afficher un aperçu du contenu (c.-à-d. afficher une petite partie du contenu avant de décider de l’acheter). Certains des paramètres uniques à chaque machine sont les suivants : sorties disponibles et statuts de protection associés, version du moteur d’exécution/client DRM disponible, niveau de sécurité du client DRM, etc. Le mode d’aperçu de licence permet au moteur d’exécution/client DRM de tester la logique métier du serveur de licences et de fournir des informations à l’utilisateur afin que ce dernier puisse prendre une décision. Le client peut donc connaître l’aspect d’une licence valide, sans pour autant recevoir la clé permettant de déchiffrer le contenu. La prise en charge du mode d’aperçu de licence est facultative et uniquement nécessaire si vous implémentez une application personnalisée qui a recours à cette fonctionnalité.
Adobe Access ne s’attache pas au mécanisme de diffusion de contenu, car Flash Player abstrait la couche de mise en réseau et se contente de diffuser le contenu protégé au sous-système de Adobe Access. Il est donc possible de diffuser le contenu via HTTP, diffusion en continu dynamique HTTP, RTMP ou RTMPE. Il est toutefois possible que des problèmes se produisent en raison de la nécessité d’obtenir les métadonnées du contenu protégé (en général sous forme de fichier .metadata) avant qu’Adobe Access ne puisse acquérir une licence pour déchiffrer le contenu. Plus spécifiquement, avec le protocole RTMP/RTMPE, seules les données FLV et F4V peuvent être diffusées au client via Flash Media Server (FMS). Le client doit par conséquent utiliser d’autres moyens de récupérer l’objet BLOB de métadonnées. Pour résoudre ce problème, il est possible d’héberger les métadonnées sur un serveur Web HTTP et d’implémenter le lecteur vidéo client en vue de récupérer les métadonnées correspondantes, en fonction du contenu en cours de lecture. private function getMetadata():void{ extrapolated-path-to-metadata = "http://metadatas.mywebserver.com/" + videoname; var urlRequest : URLRequest = new URLRequest(extrapolated-path-to-the-metadata + ".metadata"); var urlStream : URLStream = new URLStream(); urlStream.addEventListener(Event.COMPLETE, handleMetadata); urlStream.addEventListener(IOErrorEvent.NETWORK_ERROR, handleIOError); urlStream.addEventListener(IOErrorEvent.IO_ERROR, handleIOError); urlStream.addEventListener(IOErrorEvent.VERIFY_ERROR, handleIOError); try{ urlStream.load(urlRequest); }catch(se:SecurityError){ videoLog.text += se.toString() + "\n"; }catch(e:Error){ videoLog.text += e.toString() + "\n"; } 3 Dans le gestionnaire d’événement, obtenez l’occurrence de DRMTrait. DRMTrait est l’interface par le biais de
DRMTrait. private function onDRMCapabilityChange (event :MediaPlayerCapabilityChangeEvent) :void WebKit et du module d’extension du navigateur Adobe® Reader®. Dans une application AIR, le contenu PDF peut s’étendre sur toute la hauteur et toute la largeur de votre application ou bien sur une partie de l’interface. Les contrôles du module d’extension du navigateur Adobe Reader affichent les fichiers PDF dans une application AIR. Les modifications apportées à l’interface de la barre d’outils de Reader (les contrôles de position, d’ancrage et de visibilité, par exemple) sont réactivées lors de l’affichage ultérieur de fichiers PDF dans les applications AIR et le navigateur. Important : pour afficher un contenu PDF dans AIR, l’utilisateur doit avoir installé Adobe Reader ou Adobe® Acrobat® version 8.1 (ou une version ultérieure).
Si l’utilisateur ne dispose pas d’Adobe Reader ou d’Adobe Acrobat 8.1 ou ultérieur, le contenu PDF ne s’affiche pas dans une application AIR. Pour vous rendre compte si un utilisateur est en mesure de produire un contenu PDF, il faut d’abord vérifier la propriété HTMLLoader.pdfCapability. Elle est définie sur l’une des constantes suivantes de la classe HTMLPDFCapability : Constante
Acrobat tandis qu’ils exécutent leur application. Vous pourriez afficher ces instructions si le contenu PDF ne se charge pas dans un délai raisonnable. Sous Linux, AIR recherche Adobe Reader dans le chemin exporté par l’utilisateur (s’il contient la commande acroread) et dans le répertoire /opt/Adobe/Reader. Le code suivant détecte si un utilisateur est en mesure d’afficher les contenus PDF dans une application AIR. Si tel n’est pas le cas, le code recherche le code d’erreur correspondant à l’objet d’erreur HTMLPDFCapability : if(HTMLLoader.pdfCapability == HTMLPDFCapability.STATUS_OK) { trace("PDF content can be displayed"); } else { trace("PDF cannot be displayed. Error code:", HTMLLoader.pdfCapability); L’exemple suivant charge un PDF à partir d’un site externe. Remplacez l’URLRequest par le chemin qui mène à un PDF externe disponible. var request:URLRequest = new URLRequest("http://www.example.com/test.pdf"); pdf = new HTMLLoader(); pdf.height = 800; pdf.width = 600; pdf.load(request); container.addChild(pdf);
Pour plus d’informations sur les modèles d'URL d'AIR, voir « Modèles d’URI » à la page 845.
Les extensions JavaScript incorporées dans Acrobat fournissent les fonctions suivantes, entre autres :
• Traitement des formulaires au sein du document • Contrôle des événements multimédia Des détails complets sur les extensions de JavaScript pour Adobe Acrobat se trouvent sur le site Adobe Acrobat Developer Connection à l’adresse http://www.adobe.com/devnet/acrobat/javascript.html.
JavaScript dans une page HTML peut envoyer un message à JavaScript dans un contenu PDF par un appel à la méthode postMessage() de l’objet DOM représentant le contenu PDF. Par exemple, examinez le contenu PDF intégré cidessous : <object id="PDFObj" data="test.pdf" type="application/pdf" width="100%" height="100%"/>
PDF dans certains contextes au niveau du document, du dossier, de la page, du champ ou du lot. Nous n’aborderons ici que le contexte au niveau du document, celui qui définit les scripts qui sont évalués lorsque le document PDF s’ouvre. Un fichier PDF peut ajouter une propriété messageHandler à l’objet hostContainer. La propriété messageHandler est un objet qui définit les fonctions du gestionnaire pour répondre aux messages. Par exemple, le code ci-dessous définit la fonction appelée à répondre aux messages provenant du fichier PDF du conteneur hôte. Celui-ci constitue le contenu HTML qui a intégré le fichier PDF : this.hostContainer.messageHandler = {onMessage: myOnMessage}; function myOnMessage(aMessage) { if(aMessage[0] == "testMsg") { app.alert("Test message: " + aMessage[1]); } else Le code ActionScript (dans un contenu SWF) ne peut pas communiquer directement avec JavaScript dans un contenu PDF. Toutefois, ActionScript peut communiquer avec le JavaScript de la page HTML chargée dans un objet HTMLLoader qui charge le contenu PDF. Ce code JavaScript peut communiquer avec le JavaScript dans le fichier PDF chargé. Pour plus d’informations, voir « Programmation HTML et JavaScript dans AIR » à la page 1019.
Le contenu PDF dans Adobe AIR a les limites suivantes :
• Le contenu du PDF n’est visible que lorsque la propriété scaleMode de l’objet Stage de l’objet NativeWindow renfermant le contenu PDF est définie sur StageScaleMode.NO_SCALE. Lorsqu’elle est définie sur une autre valeur, le contenu PDF n’est pas visible.
PDF. Un clic sur des liens pointant vers le contenu hors d’un fichier PDF réoriente l’objet HTMLLoader qui contient le PDF, même si la cible d’un lien est une nouvelle fenêtre.
« Gestion des événements » à la page 129.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’interaction utilisateur, au moyen du clavier, de la souris, de la caméra ou d’une combinaison de ces périphériques, est à la base de l’interactivité. Dans ActionScript 3.0, l’identification et la réponse à l’interaction utilisateur impliquent principalement l’écoute d’événements. La classe InteractiveObject, une sous-classe de la classe DisplayObject, fournit la structure d’événements courante et la fonctionnalité nécessaire à la gestion de l’interaction utilisateur. Vous ne créez pas directement une occurrence de la classe InteractiveObject. Affichez plutôt des objets tels SimpleButton, Sprite, TextField et ainsi des composants divers de l’outil de programmation Flash et de Flex héritent leur modèle d’interaction utilisateur à partir de cette classe. Ils partagent alors une structure commune. Cela signifie que les techniques que vous apprenez et le code que vous écrivez pour gérer l’interaction utilisateur dans un objet dérivé de InteractiveObject sont applicables à tous les autres. Concepts importants et terminologie Il est important que vous vous familiarisiez avec les termes d’interaction utilisateur suivants avant de poursuivre : Code de caractère Code numérique représentant un caractère dans le jeu de caractères actuel (associé à une touche tapée sur le clavier). Par exemple, D et d ont des codes de caractères différents même si elles sont créées par la même touche sur un clavier français. Menu contextuel Menu qui apparaît lorsqu’un utilisateur clique avec le bouton droit de la souris ou utilise une combinaison clavier-souris particulière. Les commandes de menu contextuel s’appliquent généralement directement à l’élément sur lequel vous avez cliqué. Par exemple, un menu contextuel pour une image peut contenir une commande pour afficher l’image dans une fenêtre séparée et une commande pour la télécharger. Cible d’action Indication qu’un élément sélectionné est actif et qu’il est la cible d’une interaction clavier ou souris. Code de touche Code numérique correspondant à une touche physique du clavier.
InteractiveObject Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Un objet interactif peut recevoir le focus, soit par programmation, soit par le biais d’une action utilisateur. En outre, si la propriété tabEnabled a la valeur true, l’utilisateur peut transmettre le focus d’un objet à un autre en appuyant sur la touche Tabulation. La valeur tabEnabled est false par défaut, excepté dans les cas suivants :
• Pour un champ de texte d’entrée, la valeur est true. • Pour un objet Sprite ou MovieClip dont buttonMode a la valeur true, la valeur est true. Dans chacune de ces situations, vous pouvez ajouter un écouteur pour FocusEvent.FOCUS_IN ou FocusEvent.FOCUS_OUT pour étendre les comportements possibles lors du changement de focus. Si cette technique est pratique pour les champs texte et les formulaires, vous pouvez aussi l’utiliser avec les sprites, les clips et tout autre objet qui hérite de la classe InteractiveObject. L’exemple suivant montre comment activer le changement de focus avec la touche de tabulation et comment répondre à l’événement focus qui en découle. Dans ce cas, chaque carré change de couleur lorsqu’il reçoit le focus. Remarque : Flash Professional utilise des raccourcis clavier pour gérer le focus. Par conséquent, pour simuler correctement la gestion du focus, les fichiers SWF doivent être testés dans un navigateur ou dans AIR plutôt que dans Flash. var var var var var var for {
• propose à l’utilisateur un clavier virtuel ou physique (ou bien aucun clavier) ; • affiche un curseur (si tel n’est pas le cas, les fonctions qui s’appuient sur le survol d’un objet par le curseur ne fonctionnent pas). Les API de découverte de la saisie d’ActionScript sont les suivantes :
Capabilities.touchscreenType.
Dernière mise à jour le 27/4/2013
à la page 129. Pour plus d’informations sur l’identification du clavier pris en charge (physique, virtuel, alphanumérique, numérique à 12 touches, etc.) à l’exécution, voir « Découverte des types de saisie » à la page 576. Grâce à un IME (Input Method Editor), l’utilisateur est en mesure de taper des caractères et des symboles complexes sur un clavier standard. L’utilisation des classes IME permet à l’utilisateur de bénéficier de l’IME système dans une application.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les objets d’affichage qui héritent de leur modèle d’interaction de la classe InteractiveObject peuvent répondre à des événements de clavier à l’aide d’écouteurs d’événement. Par exemple, vous pouvez placer un écouteur d’événement sur la scène pour écouter et répondre à une saisie au clavier. Dans le code suivant, un écouteur d’événement capture une saisie au clavier et le nom et les propriétés de code de la touche sont affichés : function reportKeyDown(event:KeyboardEvent):void { trace("Key Pressed: " + String.fromCharCode(event.charCode) + " (character code: " + event.charCode + ")"); } stage.addEventListener(KeyboardEvent.KEY_DOWN, reportKeyDown);
Dans l’exemple de code précédent, l’écouteur d’événement de clavier a capturé une saisie au clavier pour la scène entière. Vous pouvez également écrire un écouteur d’événement pour un objet d’affichage spécifique sur la scène ; cet écouteur d’événement est déclenché lorsque l’objet a le focus. Dans l’exemple suivant, les frappes de touches apparaissent dans le panneau Sortie uniquement lorsque l’utilisateur tape dans l’occurrence de TextField. S’il maintient la touche Maj enfoncée, la couleur du contour du TextField devient temporairement rouge. Ce code suppose qu’il existe une occurrence de TextField appelée tf sur la scène.
{ trace("Key Pressed: " + String.fromCharCode(event.charCode) + " (key code: " + event.keyCode + " character code: " + event.charCode + ")"); if (event.keyCode == Keyboard.SHIFT) tf.borderColor = 0xFF0000; Codes de touches et de caractères Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les propriétés keyCode et charCode d’un événement clavier permettent de déterminer la touche utilisée et de déclencher d’autres actions. La propriétékeyCode est une valeur numérique qui correspond à la valeur de la touche sur le clavier. La propriété charCode est la valeur numérique de cette touche dans le jeu de caractères actuel (le jeu de caractères par défaut est UTF-8, qui prend en charge ASCII). La différence principale entre le code de touche et les valeurs de caractères est la suivante : la valeur du code de touche représente une touche déterminée du clavier (la touche 1 sur le pavé numérique est différente du 1 sur le clavier central, mais cette dernière permet à la fois de générer 1 et &) alors que la valeur du caractère représente un caractère particulier (les caractères R et r sont différents). Remarque : pour plus d’informations sur le mappage entre les touches et le code de caractère ASCII correspondant, voir la classe flash.ui.Keyboard dans le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash. Les mappages entre les touches et leurs codes de touches dépendent du périphérique et du système d’exploitation. C’est pourquoi vous ne devez pas utiliser de mappages de touches pour déclencher des actions. A la place, utilisez les valeurs de constante prédéfinies fournies par la classe Keyboard pour référencer les propriétés keyCode appropriées. Par exemple, au lieu d’utiliser le mappage de touche pour la touche Maj, utilisez la constante Keyboard.SHIFT (comme indiqué dans l’exemple de code précédent).
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Comme avec d’autres événements, la séquence d’événement de clavier est déterminée par la hiérarchie d’objet d’affichage et non par l’ordre dans lequel les méthodes addEventListener() sont affectées dans le code. Supposons par exemple que vous placiez un champ de texte tf au sein d’un clip nommé container et que vous ajoutiez un écouteur d’événement pour l’événement de clavier à chaque occurrence, comme indiqué dans l’exemple suivant : container.addEventListener(KeyboardEvent.KEY_DOWN,reportKeyDown); container.tf.border = true; container.tf.type = "input"; container.tf.addEventListener(KeyboardEvent.KEY_DOWN,reportKeyDown); function reportKeyDown(event:KeyboardEvent):void { trace(event.currentTarget.name + " hears key press: " + String.fromCharCode(event.charCode) + " (key code: " + event.keyCode + " character code: " + event.charCode + ")"); } Par exemple, dans Microsoft Internet Explorer, lorsque vous appuyez sur Ctrl+W, vous fermez la fenêtre du navigateur avant qu’un fichier SWF contenu ne distribue un événement de clavier.
La classe IME permet de manipuler l’IME du système d’exploitation à partir de Flash Player ou Adobe AIR. A l’aide d’ActionScript, vous pouvez déterminer les éléments suivants :
• Si l’IME est activé ou désactivé sur l’ordinateur de l’utilisateur (IME.enabled) • Le mode de conversion utilisé par l’IME actif (IME.conversionMode) Vous pouvez associer un champ de saisie de texte à un contexte IME particulier. Lorsque vous passez d’un champ de saisie à un autre, vous pouvez également changer l’IME pour utiliser les caractères Hiragana (japonais), des nombres à pleine chasse, des nombres à demi-chasse, la saisie directe, etc. Un IME permet aux utilisateurs d’entrer des caractères de texte non ASCII des langues codées sur plusieurs octets, telles que le chinois, le japonais et le coréen. Pour plus d’informations sur les IME, voyez la documentation du système d’exploitation correspondant à la plateforme pour laquelle vous développez l’application. Pour davantage de ressources, voir également les sites Web suivants :
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lorsque vous construisez une application multilingue, il peut être nécessaire de déterminer le mode de conversion actif dans le système d’exploitation. Le code suivant montre comment vérifier si l’utilisateur dispose d’un IME installé et, le cas échéant, quel mode de conversion IME est activé :
Lorsque vous modifiez le mode de conversion de l’IME de l’utilisateur, veillez à ce que le code soit enveloppé dans un bloc try..catch, car la définition du mode de conversion à l’aide de la propriété conversionMode peut donner lieu à une erreur si l’IME ne peut pas définir le mode choisi. Le code suivant illustre l’utilisation d’un bloc try..catch lors de la définition de la propriétéIME.conversionMode :
Le bloc try..catch affiche le message d’erreur dans le champ de texte créé précédemment.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Dans certains cas, il peut être nécessaire de désactiver l’IME de l’utilisateur pendant que ce dernier saisit des caractères. Par exemple, si un champ de texte accepte uniquement des caractères numériques, il peut être préférable d’éviter l’intervention de l’IME pour ne pas ralentir la saisie des données. L’exemple suivant montre comment écouter les événements FocusEvent.FOCUS_IN et FocusEvent.FOCUS_OUT et désactiver l’IME de l’utilisateur en conséquence :
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les événements IME composition sont distribués lors de la définition d’une chaîne de composition. Par exemple, si l’IME de l’utilisateur est activé et que l’utilisateur saisit une chaîne en japonais, l’événement IMEEvent.IME_COMPOSITION est distribué dès que l’utilisateur sélectionne la chaîne de composition. Pour écouter l’événement IMEEvent.IME_COMPOSITION, vous devez ajouter un écouteur d’événement à la propriété statique ime de la classe System (flash.system.System.ime.addEventListener(...)), comme le montre l’exemple suivant :
• détecter le moment où le clavier virtuel apparaît et le moment où il disparaît ; • empêcher le clavier de s’afficher ;
• créer des objets interactifs qui affichent le clavier lorsqu’ils prennent le focus ; (non pris en charge par les applications AIR sous iOS)
Le moteur d’exécution ouvre automatiquement le clavier virtuel lorsque l’utilisateur appuie dans un champ de texte ou un objet interactif spécialement configuré. A l’ouverture du clavier, le moteur d’exécution respecte les conventions de la plate-forme native en matière de panoramique et de redimensionnement du contenu de l’application, afin que l’utilisateur puisse visualiser le texte au fur et à mesure qu’il le tape. A l’ouverture du clavier, l’objet cible d’action distribue les événements suivants dans l’ordre indiqué : Evénement softKeyboardActivating : distribué juste avant que le clavier ne commence à se superposer à la scène. Si vous appelez la méthode preventDefault() de l’objet événement distribué, le clavier virtuel ne s’ouvre pas. Evénement softKeyboardActivate : distribué au terme du traitement de l’événement softKeyboardActivating. Lorsque l’objet cible d’action distribue cet événement, la propriété softKeyboardRect de l’objet Stage a été mise à jour pour refléter la partie de la scène masquée par le clavier virtuel. Il est impossible d’annuler cet événement. Remarque : en cas de changement de taille du clavier (si l’utilisateur modifie le type du clavier, par exemple), l’objet cible d’action distribue un second événement softKeyboardActivate. Evénement softKeyboardDeactivate : distribué lors de la fermeture du clavier virtuel, quel qu’en soit le motif. Il est impossible d’annuler cet événement. L’exemple suivant ajoute deux objets TextField sur la scène. L’objet TextField supérieur interdit l’affichage du clavier lorsque vous touchez le champ et le ferme s’il est déjà affiché. L’objet TextField inférieur illustre le comportement par défaut. L’exemple indique les événements de clavier logiciel distribués par les deux champs de texte. package { import flash.display.Sprite; import flash.text.TextField; import flash.text.TextFieldType; import flash.events.SoftKeyboardEvent; public class SoftKeyboardEventExample extends Sprite { private var tf1:TextField = new TextField(); private var tf2:TextField = new TextField(); public function SoftKeyboardEventExample() { tf1.width = this.stage.stageWidth; tf1.type = TextFieldType.INPUT; tf1.border = true; this.addChild( tf1 ); tf1.addEventListener( SoftKeyboardEvent.SOFT_KEYBOARD_ACTIVATING, preventSoftKe yboard ); tf1.addEventListener( SoftKeyboardEvent.SOFT_KEYBOARD_ACTIVATE, preventSoftKe yboard ); tf1.addEventListener( SoftKeyboardEvent.SOFT_KEYBOARD_DEACTIVATE, preventSoftKeyboard En temps normal, le clavier virtuel ne s’ouvre que si l’utilisateur appuie sur un objet TextField. Vous pouvez configurer une occurrence de la classe InteractiveObject de façon à ouvrir le clavier virtuel lorsqu’il reçoit le focus. Pour configurer une occurrence d’InteractiveObject de façon à ouvrir le clavier logiciel, définissez la propriété needsSoftKeyboard sur true. Dès que l’objet est affecté à la propriété focus de la scène, le clavier logiciel s’ouvre automatiquement. Par ailleurs, vous pouvez afficher le clavier en appelant la méthode requestSoftKeyboard() de l’objet InteractiveObject. L’exemple suivant explique comment programmer un objet InteractiveObject de façon à ce qu’il se comporte comme un champ de saisie de texte. La classe TextInput décrite dans l’exemple définit la propriété needsSoftKeyboard de façon à ce que le clavier s’affiche lorsque cela est nécessaire. L’objet écoute alors les événements keyDown et insère le caractère saisi dans le champ. Cet exemple fait appel au moteur de texte de Flash pour ajouter et afficher le texte saisi, et gère quelques événements importants. Pour plus de simplicité, cet exemple n’implémente pas un champ de texte complet.
Dans une application réelle, vous auriez besoin d’un algorithme de mise en forme plus sophistiqué. package
<softKeyboardBehavior>none</softKeyboardBehavior>
(Lorsque le clavier est fermé, les dimensions du rectangle softKeyboardRect sont toutes égales à zéro.) Lors de la fermeture du clavier, un événement softKeyboardDeactivate est distribué et vous pouvez réactiver l’affichage normal de l’application. package { import import import import import import import import
Pour plus d’informations sur l’identification du type de souris pris en charge (curseur permanent, stylet, action tactile, etc.) à l’exécution, voir « Découverte des types de saisie » à la page 576.
« Saisie tactile, multipoint et par mouvement » à la page 600
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les clics de souris créent des événements souris qui permettent de déclencher une fonctionnalité interactive. Il est possible d’ajouter un écouteur d’événement à la scène afin d’écouter les événements de souris qui se produisent à tout endroit du fichier SWF. Vous pouvez également ajouter des écouteurs d’événement à des objets sur la scène qui héritent de InteractiveObject (par exemple, Sprite ou MovieClip) ; ces écouteurs sont déclenchés lorsque vous cliquez sur l’objet. Comme les événements de clavier, les événements de souris se propagent vers le haut. Dans l’exemple suivant, square étant un enfant de la scène, l’événement est distribué à la fois du sprite square et de l’objet scène en cas de clic sur le carré : var square:Sprite = new Sprite(); square.graphics.beginFill(0xFF0000); square.graphics.drawRect(0,0,100,100); square.graphics.endFill(); square.addEventListener(MouseEvent.CLICK, reportClick); square.x = square.y = 50; addChild(square); stage.addEventListener(MouseEvent.CLICK, reportClick); function reportClick(event:MouseEvent):void { trace(event.currentTarget.toString() + " dispatches MouseEvent. Local coords [" + event.localX + "," + event.localY + "] Stage coords [" + event.stageX + "," + event.stageY + "]"); }
Remarque : en mode plein écran, vous pouvez configurer l’application de façon à activer le verrouillage de la souris. Le verrouillage de la souris désactive le curseur et permet de déplacer la souris sans aucune limite. Pour plus d’informations, voir « Utilisation du mode Plein écran » à la page 173. L’objet MouseEvent contient aussi les propriétés booléennes altKey, ctrlKey et shiftKey. Vous pouvez utiliser ces propriétés pour vérifier si l’utilisateur appuie également sur la touche Alt, Ctrl ou Maj au moment du clic de la souris.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous pouvez autoriser les utilisateurs à faire glisser un objet Sprite sur la scène à l’aide de la méthode startDrag() de la classe Sprite. Le code suivant en est un exemple :
Opération glisser-déposer dans AIR Vous pouvez activer la prise en charge d’opérations glisser-déposer dans Adobe AIR pour permettre aux utilisateurs de faire glisser des données vers l’application et en dehors de celle-ci. Pour plus d’informations, voir « Opération glisser-déposer dans AIR » à la page 629.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le curseur de la souris (pointeur de la souris) peut être masqué ou remplacé pour tout objet d’affichage de la scène. Pour masquer ce curseur, appelez la méthode Mouse.hide(). Personnalisez le curseur en appelant Mouse.hide(), en écoutant l’événement MouseEvent.MOUSE_MOVE en provenance de la scène et en définissant les coordonnées d’un objet d’affichage (votre curseur personnalisé) sur les propriétés stageX et stageY de l’événement. L’exemple suivant illustre une exécution de base de cette tâche :
Pour obtenir les fichiers d’application de cet exemple, voir www.adobe.com/go/learn_programmingAS3samples_flash_fr. Les fichiers d’application WordSearch se trouvent dans le dossier Samples/WordSearch. L’application se compose des fichiers suivants : Fichier
Pour créer un jeu qui implique la recherche de mots, un dictionnaire est nécessaire. L’exemple inclut un fichier texte appelé dictionary.txt, qui contient une liste de mots séparés par des retours à la ligne. Après avoir créé un tableau appelé words, la fonction loadDictionary() demande ce fichier. Une fois chargé, celui-ci devient une longue chaîne. Vous pouvez convertir cette chaîne en un tableau de mots grâce à la méthode split(), qui s’arrête à chaque occurrence d’un retour à la ligne (code de caractère 10) ou d’une nouvelle ligne (code de caractère 13). Cette analyse a lieu dans la fonction dictionaryLoaded() :
Dans la fonction setupUI(), ce code crée les écouteurs sur les deux boutons : submitWordButton.addEventListener(MouseEvent.CLICK,submitWord); clearWordButton.addEventListener(MouseEvent.CLICK,clearWord);
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le tableau de jeu est une grille de lettres aléatoires. Dans la fonction generateBoard(), une grille en deux dimensions est créée en imbriquant une boucle dans une autre. La première boucle incrémente les lignes et la seconde le nombre totale de colonnes par ligne. Chaque cellule créée par ces lignes et ces colonnes contient un bouton qui représente une lettre sur le tableau. private function generateBoard(startX:Number, startY:Number, totalRows:Number, totalCols:Number, buttonSize:Number):void { buttons = new Array(); var colCounter:uint; var rowCounter:uint; for (rowCounter = 0; rowCounter < totalRows; rowCounter++) { for (colCounter = 0; colCounter < totalCols; colCounter++) { var b:Button = new Button(); b.x = startX + (colCounter*buttonSize); b.y = startY + (rowCounter*buttonSize); b.addEventListener(MouseEvent.CLICK, letterClicked); b.label = getRandomLetter().toUpperCase(); b.setSize(buttonSize,buttonSize); b.name = "buttonRow"+rowCounter+"Col"+colCounter; addChild(b); buttons.push(b); Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les mots peuvent être écrits en sélectionnant des lettres adjacentes verticalement ou horizontalement, mais jamais en utilisant deux fois la même lettre. Chaque clic génère un événement de souris au niveau duquel le mot qu’écrit l’utilisateur doit être vérifié pour s’assurer qu’il se poursuit correctement à partir de lettres cliquées précédemment. Si ce n’est pas le cas, le mot précédent est supprimé et un nouveau est commencé. Cette vérification s’effectue dans la méthode isLegalContinuation(). private { var 3)); var 3)); var Pour terminer le code pour le jeu, des mécanismes permettant de vérifier des mots soumis et de gérer le score sont nécessaires. La méthode searchForWord() permet ces deux opérations :
Il existe plusieurs constantes au début de la classe. Vous pouvez modifier ce jeu en changeant ces variables. Il est par exemple possible de modifier le temps de jeu disponible en augmentant la variable TOTAL_TIME. Si vous augmentez légèrement la variable PERCENT_VOWELS, vous pouvez accroître la probabilité de trouver des mots.
Saisie tactile Saisie par le biais d’un périphérique à point unique tel un doigt, un stylet ou un autre outil sur un périphérique tactile. Certains périphériques prennent en charge plusieurs points de contacts simultanés par le biais d’un doigt ou d’un stylet. Saisie multipoint Saisie caractérisée par plusieurs points de contact simultanés. Mouvement Saisie interprétée par un périphérique ou un système d’exploitation en réponse à un ou plusieurs événements tactiles. Un utilisateur tourne simultanément deux doigts, par exemple, et le périphérique ou le système d’exploitation interprète cette saisie tactile comme un mouvement de rotation. Certains mouvements sont exécutés à l’aide d’un doigt ou d’un point tactile, tandis que d’autres mouvements en requièrent plusieurs. Le périphérique ou le système d’exploitation détermine le type de mouvement à affecter à la saisie.
Remarque : selon le périphérique et le système d’exploitation utilisés, l’écoute des événements tactiles et de mouvement sollicite parfois un volume important de ressources de traitement (équivalent au rendu de plusieurs images par seconde). Il est souvent préférable de faire appel à des événements de souris si les fonctionnalités complémentaires assurées par la saisie tactile ou les mouvements ne sont pas nécessaires. Si vous utilisez des événements tactiles ou de mouvement, envisagez de réduire le nombre de modifications graphiques susceptibles de se produire, en particulier si ces événements peuvent être distribués rapidement, comme cela se produit lors d’une opération de type panoramique, rotation ou zoom. Vous pourriez, par exemple, arrêter l’animation au sein d’un composant pendant que l’utilisateur le redimensionne par le biais d’un mouvement de zoom.
Paul Trani : Touch Events and Gestures on Mobile (disponible en anglais uniquement) Mike Jones: Virtual Game Controllers (disponible en anglais uniquement) Flash Player 10.1 et les versions ultérieures, Adobe AIR 2 et les versions ultérieures Lorsque la plate-forme Flash s’exécute dans un environnement qui prend en charge la saisie tactile, les occurrences d’InteractiveObject peuvent écouter les événements tactiles et les gestionnaires d’appel. En règle générale, les événements tactiles, multipoint et de mouvement sont traités comme tout autre événement en ActionScript (pour obtenir des informations de base sur la gestion des événements en ActionScript, voir « Gestion des événements » à la page 129). Toutefois, pour que le moteur d’exécution de Flash puisse interpréter une action tactile ou un mouvement, il doit s’exécuter dans un environnement matériel et logiciel qui prend en charge la saisie tactile ou multipoint. Pour visualiser un graphique qui compare les différents types d’écran tactile, voir « Découverte des types de saisie » à la page 576. Par ailleurs, si le moteur d’exécution s’exécute dans une application conteneur (un navigateur, par exemple), celle-ci transmet la saisie au moteur d’exécution. Dans certains cas, l’environnement actuel caractérisé par le matériel et le système d’exploitation prend en charge la saisie multipoint, mais le navigateur qui contient le moteur d’exécution interprète la saisie et ne la transmet pas à ce dernier. Il peut également ignorer totalement la saisie. Le diagramme suivant illustre le flux des saisies de l’utilisateur au moteur d’exécution :
Concepts importants et terminologie La liste de référence suivante contient des termes importants relatifs à la programmation d’une application de gestion des événements tactile : API de découverte Méthodes et propriétés destinées à vérifier si l’environnement d’exécution prend en charge les
Evénement tactile Action de saisie exécutée sur un périphérique tactile basée sur un point de contact unique. Point tactile Point de contact associé à un événement tactile unique. Même si un périphérique ne prend pas en charge la saisie par mouvement, il est susceptible de gérer les points tactiles simultanés multiples. Séquence tactile Série d’événements qui représentent la durée de vie d’une action tactile unique. Ces événements comprennent un début, zéro, une ou plusieurs actions et une fin. Evénement multipoint Action de saisie exécutée sur un périphérique tactile basée sur plusieurs points de contact (plusieurs doigts, par exemple). Evénement de mouvement Action de saisie exécutée sur un périphérique tactile qui trace un mouvement complexe.
Saisie tactile, multipoint et par mouvement
Stylet Instrument d’interaction avec un écran tactile. Un stylet est souvent plus précis que le doigt. Certains périphériques ne gèrent qu’un type déterminé de stylet. Les périphériques qui reconnaissent la saisie par stylet risquent de ne pas gérer les points de contact multiples et simultanés ou le contact d’un doigt. Appui-appui bref Type déterminé de mouvement de saisie multipoint caractérisé comme suit : l’utilisateur place un
De par sa conception, l’API de gestion de la saisie tactile d’ActionScript tient compte du fait que le traitement de la saisie tactile varie selon l’environnement matériel et logiciel du moteur d’exécution de Flash. Elle traite principalement trois besoins du développement d’applications tactiles : la découverte, les événements et les phases. La coordination de ces API assure à l’utilisateur une expérience prévisible et réactive, même si le périphérique cible est inconnu lors du développement de l’application.
L’API de découverte permet de tester l’environnement matériel et logiciel à l’exécution. Les valeurs renseignées par le moteur d’exécution déterminent les saisies tactiles dont dispose le moteur d’exécution de Flash dans le contexte actuel. Vous disposez également du jeu de propriétés et méthodes de découverte pour définir l’application de sorte qu’elle réagisse aux événements de souris (au lieu des événements tactiles lorsque certains types de saisie tactile ne sont pas pris en charge par l’environnement). Pour plus d’informations, voir « Découverte de la prise en charge des actions tactiles » à la page 603.
A l’instar de tout autre événement, ActionScript gère les événements tactiles par le biais d’écouteurs et de gestionnaires d’événement. Toutefois, la gestion des événements tactiles doit également prendre en compte les éléments suivants :
événements tactiles. Vous pouvez également créer une application qui réagit aux deux types d’événements.
L’API de découverte permet généralement de traiter de manière conditionnelle les événements gérés par l’application, ainsi que leur mode de traitement. Lorsque l’application connaît l’environnement d’exécution, elle peut appeler le gestionnaire approprié ou déterminer l’objet d’événement requis quand l’utilisateur interagit avec l’application. L’application peut également indiquer qu’une saisie spécifique ne peut pas être traitée dans l’environnement actuel et proposer à l’utilisateur une autre solution ou des informations. Pour plus d’informations, voir « Gestion des événements tactiles » à la page 604 et « Gestion des événements de mouvement » à la page 609.
Vous pouvez également faire appel aux phases pour suivre des propriétés déterminées d’un mouvement au fur et à mesure que celui-ci évolue. Pour les événements de point tactile, vérifiez la durée de l’appui de l’utilisateur sur un objet interactif donné. Une application peut suivre plusieurs phases de points tactiles simultanées à titre individuel et les traiter en conséquence. Pour un mouvement, interprétez les informations spécifiques relatives à la transformation du mouvement lorsqu’elle se produit. Suivez les coordonnées du ou des points de contact lorsqu’ils se déplacent à l’écran.
Flash Player 10.1 et les versions ultérieures, Adobe AIR 2 et les versions ultérieures Pour définir l’étendue de la saisie tactile traitée par l’application, faites appel aux propriétés de la classe Multitouch. Testez ensuite l’environnement pour vous assurer de la prise en charge des événements gérés par le code ActionScript. Déterminez tout d’abord le type de saisie tactile pris en charge par l’application. Les options disponibles sont touch point, gesture ou none (interprétez toute saisie tactile comme un clic de souris et n’utilisez que des gestionnaires d’événement de souris). Faites ensuite appel aux propriétés et méthodes de la classe Multitouch pour vous assurer que le moteur d’exécution tourne dans un environnement qui prend en charge la saisie tactile requise par l’application. Testez l’environnement d’exécution pour vérifier s’il prend en charge les types de saisie tactile (l’interprétation des mouvements, par exemple) et réagissez en conséquence. Remarque : la classe Multitouch contient des propriétés statiques, qui n’appartiennent à aucune occurrence de classe. Utilisez-les avec la syntaxe de Multitouch.property, par exemple : var touchSupport:Boolean = Multitouch.supportsTouchEvents;
Etant donné qu’un événement tactile se compose parfois d’un grand nombre d’éléments ou de phases, le moteur d’exécution de Flash doit pouvoir identifier le type de saisie tactile à interpréter. Si le doigt se contente de toucher un écran tactile, le moteur d’exécution distribue-t-il un événement tactile ? Attend-il plutôt un mouvement ? Le moteur d’exécution suit-il l’action tactile en tant qu’événement de bouton de souris enfoncé ? Une application qui prend en charge la saisie tactile doit déterminer le type d’événement tactile géré pour le moteur d’exécution de Flash. La propriété Multitouch.inputMode permet de déterminer le type de saisie tactile à l’intention du moteur d’exécution. Le mode de saisie correspond à l’une des trois options suivantes : Aucun (None) Les événements tactiles ne sont pas gérés différemment. Définissez comme suit cette option : Multitouch.inputMode=MultitouchInputMode.NONE et traitez la saisie à l’aide de la classe MouseEvent.
Saisie par mouvement Le périphérique ou le système d’exploitation interprète la saisie en tant que mouvement complexe du doigt à l’écran. Le périphérique ou le système d’exploitation affecte globalement le mouvement à un événement de saisie par mouvement unique. Définissez comme suit cette option :
Multitouch.inputMode en vue de définir le type de saisie avant de traiter un événement tactile.
D’autres propriétés de la classe Multitouch proposent des valeurs permettant d’adapter l’application à la prise en charge de la saisie tactile dans l’environnement actuel. Le moteur d’exécution de Flash renseigne les valeurs associées au nombre de points tactiles simultanés autorisés ou aux mouvements disponibles. Si le moteur d’exécution tourne dans un environnement qui ne prend pas en charge la gestion des événements tactiles requise par l’application, proposez une autre solution à l’utilisateur. Assurez par exemple la prise en charge des événements de souris ou affichez des informations relatives aux fonctions disponibles ou non dans l’environnement actuel. Vous disposez également de l’API de prise en charge du clavier, des actions tactiles et de la souris (voir « Découverte des types de saisie » à la page 576). Pour plus d’informations sur les tests de compatibilité, voir « Résolution des problèmes » à la page 613.
Flash Player 10.1 et les versions ultérieures, Adobe AIR 2 et les versions ultérieures ActionScript gère les événements tactiles de base comme tout autre événement (les événements de souris, par exemple). Vous pouvez écouter une série d’événements tactiles définis par les constantes de type d’événement de la classe TouchEvent. Remarque : dans le cas d’une saisie multipoint (toucher de plusieurs doigts un périphérique, par exemple), le premier point de contact distribue un événement de souris et un événement tactile. Pour gérer un événement tactile de base : 1 Activez la gestion des événements tactiles dans l’application en définissant la propriété flash.ui.Multitouch.inputMode sur MultitouchInputMode.TOUCH_POINT.
3 Indiquez le type d’événement tactile à gérer. 4 Appelez une fonction de gestionnaire d’événement en réponse à l’événement.
Ils ne prennent par conséquent pas en charge la propriété TouchEvent.pressure. Essayez de tester la prise en charge de propriétés spécifiques pour assurer le fonctionnement de l’application. Pour plus d’informations, voir « Résolution des problèmes » à la page 613.
événements tactiles du début à la fin d’une interaction tactile. La classe TouchEvent comporte des valeurs de gestion des événements touchBegin, touchMove et touchEnd. Vous disposez par exemple des événements touchBegin, touchMove et touchEnd pour proposer à l’utilisateur un feedback visuel lorsqu’il touche et déplace un objet d’affichage : Multitouch.inputMode = MultitouchInputMode.TOUCH_POINT; var mySprite:Sprite = new Sprite(); mySprite.graphics.beginFill(0x336699); mySprite.graphics.drawRect(0,0,40,40); addChild(mySprite); var myTextField:TextField = new TextField(); myTextField.width = 200; myTextField.height = 20; addChild(myTextField); mySprite.addEventListener(TouchEvent.TOUCH_BEGIN, onTouchBegin); stage.addEventListener(TouchEvent.TOUCH_MOVE, onTouchMove); stage.addEventListener(TouchEvent.TOUCH_END, onTouchEnd); function onTouchBegin(event:TouchEvent) { myTextField.text = "touch begin" + event.touchPointID; } function onTouchMove(event:TouchEvent) { myTextField.text = "touch move" + event.touchPointID; } function onTouchEnd(event:TouchEvent) { myTextField.text = "touch end" + event.touchPointID; Sprite utilisent la propriété touchPointID en tant que paramètre pour assurer le traitement de l’occurrence de saisie correcte. La propriété touchPointID vérifie qu’un gestionnaire d’événement réagit au point tactile approprié. Le gestionnaire d’événement réagit sinon à n’importe quelle occurrence du type d’événement tactile (tous les événements touchMove, par exemple) sur le périphérique, d’où un comportement imprévisible. La propriété est particulièrement importante lorsque l’utilisateur fait glisser des objets. La propriété touchPointID permet de gérer une séquence entière d’actions tactiles. Une séquence d’actions tactile se compose d’un événement touchBegin, de zéro, un ou plusieurs événements touchMove et d’un événement touchEnd, qui possèdent tous la même valeur touchPointID.
Deux méthodes ont été ajoutées à classe Sprite en vue de mieux prendre en charge les applications tactiles qui gèrent la saisie des points tactiles : Sprite.startTouchDrag() et Sprite.stopTouchDrag(). Le comportement de ces méthodes est identique à celui de Sprite.startDrag() et Sprite.stopDrag() en matière d’événements de souris. Notez toutefois que les méthodes Sprite.startTouchDrag() et Sprite.stopTouchDrag() gèrent toutes deux les valeurs touchPointID en tant que paramètres. Le moteur d’exécution affecte la valeur touchPointID à l’objet d’événement pour un événement tactile. Cette valeur permet de réagir à un point tactile spécifique si l’environnement prend en charge les points tactiles multiples et simultanés (même s’il ne gère pas les mouvements). Pour plus d’informations sur la propriété touchPointID, voir « ID de point tactile » à la page 606. Le code suivant illustre un gestionnaire d’événement start drag simple et un gestionnaire d’événement stop drag associé à un événement tactile. La variable bg est un objet d’affichage qui contient mySprite : mySprite.addEventListener(TouchEvent.TOUCH_BEGIN, onTouchBegin); mySprite.addEventListener(TouchEvent.TOUCH_END, onTouchEnd); function onTouchBegin(e:TouchEvent) { e.target.startTouchDrag(e.touchPointID, false, bg.getRect(this)); trace("touch begin"); } function onTouchEnd(e:TouchEvent) { e.target.stopTouchDrag(e.touchPointID); trace("touch end"); }
Traitez les événements de mouvement comme tout événement tactile de base. Vous pouvez écouter une série d’événements de mouvement définis par les constantes de type d’événement dans la classe TransformGestureEvent, la classe GestureEvent et la classe PressAndTapGestureEvent. Pour gérer un événement tactile de mouvement : 1 Activez la prise en charge de la saisie par mouvement dans l’application en définissant la propriété flash.ui.Multitouch.inputMode sur MultitouchInputMode.GESTURE.
3 Indiquez le type d’événement de mouvement à gérer. 4 Appelez une fonction de gestionnaire d’événement en réponse à l’événement.
TransformGestureEvent et PressAndTapGestureEvent. Ainsi, certains périphériques tactiles ne sont pas en mesure de détecter un mouvement de glissement à plusieurs doigts. Les événements gestureSwipe de la classe InteractiveObject ne sont donc pas pris en charge par ces périphériques. Essayez de vérifier la prise en charge d’événements spécifiques pour assurer le fonctionnement de l’application. Pour plus d’informations, voir « Résolution des problèmes » à la page 613.
Les événements de mouvement gèrent moins de propriétés que les événements tactiles de base. Vous y accédez de la même façon, par le biais de l’objet d’événement de la fonction du gestionnaire d’événement. Le code suivant fait par exemple pivoter mySprite lorsque l’utilisateur effectue dessus un mouvement de rotation. Le champ de texte indique le facteur de rotation appliqué depuis le dernier mouvement (lorsque vous testez ce code, faites-le pivoter plusieurs fois pour visualiser les changements de valeur) : Multitouch.inputMode=MultitouchInputMode.GESTURE; var mySprite:Sprite = new Sprite(); var mySpriteCon:Sprite = new Sprite(); var myTextField:TextField = new TextField(); myTextField.y = 50; addChild(myTextField); mySprite.graphics.beginFill(0x336699); mySprite.graphics.drawRect(-20,-20,40,40); mySpriteCon.addChild(mySprite); mySprite.x = 20; mySprite.y = 20; addChild(mySpriteCon); mySprite.addEventListener(TransformGestureEvent.GESTURE_ROTATE, rothandler); function rothandler(evt:TransformGestureEvent): void { evt.target.parent.rotationZ += evt.target.rotation; myTextField.text = evt.target.parent.rotation.toString(); }
TransformGestureEvent. Ainsi, certains périphériques tactiles ne sont pas en mesure de détecter la rotation d’un mouvement à l’écran. Ils ne prennent par conséquent pas en charge la propriété TransformGestureEvent.rotation. Essayez de tester la prise en charge de propriétés spécifiques pour assurer le fonctionnement de l’application. Pour plus d’informations, voir « Résolution des problèmes » à la page 613.
Les événements de mouvement peuvent également être suivis par phases, vous permettant ainsi de suivre les propriétés au fur et à mesure que le mouvement est exécuté. Vous pouvez par exemple suivre les coordonnées x lorsqu’un objet est déplacé par le biais d’un mouvement de glissement. Utilisez ces valeurs pour tracer une ligne qui relie tous les points de son chemin, une fois le glissement terminé. Vous pouvez également modifier visuellement un objet d’affichage lorsqu’il traverse l’écran par glissement via un mouvement panoramique. Modifiez à nouveau l’objet une fois le mouvement panoramique terminé.
Certains objets ne suivent pas chaque phase de l’événement de mouvement associé. Ils insèrent plutôt la valeur « all » dans la propriété de la phase de l’objet d’événement. Les mouvements simples tels qu’un glissement et un double appui ne suivent pas l’événement en plusieurs phases. Une fois l’événement distribué, la propriété phase de l’objet d’événement interactif qui écoute l’événement gestureSwipe ou gestureTwoFingerTap correspond toujours à all :
La prise en charge matérielle et logicielle de la saisie tactile évolue rapidement. Le présent Guide de référence ne dresse pas la liste de tous les périphériques et combinaisons système d’exploitation/logiciels qui prennent en charge la saisie multipoint. Il contient toutefois des conseils relatifs à l’utilisation de l’API de découverte pour déterminer si le périphérique sur lequel est déployée l’application prend en charge la saisie multipoint, et propose des conseils de résolution des problèmes dans le code ActionScript. Les moteurs d’exécution de Flash réagissent aux événements tactiles en fonction des informations transmises au moteur d’exécution par le périphérique, le système d’exploitation ou un logiciel conteneur (un navigateur, par exemple). Cette dépendance vis-à-vis de l’environnement logiciel complique la présentation de la compatibilité multipoint. L’interprétation d’un mouvement ou d’une action tactile varie parfois selon le périphérique. Une rotation consiste-t-elle en deux doigts qui pivotent simultanément ? Ou en un doigt qui trace un cercle à l’écran ? Selon l’environnement matériel et logiciel utilisé, le mouvement de rotation peut correspondre à l’un des deux cas de figure ou à une action totalement différente. Le périphérique indique la saisie utilisateur au système d’exploitation, qui transmet cette information au moteur d’exécution. Si le moteur d’exécution tourne dans un navigateur, ce dernier interprète parfois l’événement tactile ou de mouvement et ne transmet pas la saisie au moteur d’exécution. Ce comportement est similaire à celui des « touches de fonction » : vous essayez d’utiliser une combinaison de touches déterminée pour demander à Flash Player d’effectuer une action donnée dans le navigateur, au lieu de quoi ce dernier ouvre un menu. Chaque API et classe indique si elle n’est pas compatible avec certains systèmes d’exploitation. Le cas échéant, passez en revue les entrées consacrées aux API, à commencer par la classe Multitouch : http://help.adobe.com/fr_FR/FlashPlatform/reference/actionscript/3/flash/ui/Multitouch.html. Quelques mouvements et actions tactiles courants sont décrits ci-après : Panoramique Déplacez un doigt de gauche à droite ou de droite à gauche. Certains périphériques requièrent
Rotation Touchez l’écran de deux doigts, puis déplacez-les en formant un cercle (comme s’ils traçaient simultanément
Zoom Touchez l’écran de deux doigts, puis séparez-les pour effectuer un zoom avant ou rapprochez-les pour effectuer un zoom arrière. Appui-appui bref Déplacez ou appuyez un doigt, puis appuyez brièvement d’un doigt sur la surface.
Si l’application ne réagit pas aux événements tactiles ou aux mouvements, vérifiez les éléments suivants : 1 Des écouteurs d’événements tactiles ou de mouvement sont-ils associés à une classe d’objet qui hérite de la classe
2 Testez-vous l’application avec Flash Professional CS5 ? Si tel est le cas, essayez de publier et de tester l’application,
3 Commencez par des événements simples et identifiez les événements pris en charge (l’exemple de code suivant est
Multitouch.inputMode=MultitouchInputMode.TOUCH_POINT; var mySprite:Sprite = new Sprite(); var myTextField:TextField = new TextField() mySprite.graphics.beginFill(0x336699); mySprite.graphics.drawRect(0,0,40,40); addChild(mySprite); mySprite.addEventListener(TouchEvent.TOUCH_TAP, taplistener); function taplistener(e:TouchEvent): void { myTextField.text = "I've been tapped"; myTextField.y = 50; addChild(myTextField); } Procédez comme suit pour tester simplement le mouvement de zoom : Multitouch.inputMode = MultitouchInputMode.GESTURE; stage.addEventListener(TransformGestureEvent.GESTURE_ZOOM , onZoom); var myTextField = new TextField(); myTextField.y = 200; myTextField.text = "Perform a zoom gesture"; addChild(myTextField); function onZoom(evt:TransformGestureEvent):void { myTextField.text = "Zoom is supported"; }
partie de l’application test. Procédez comme suit pour tester simplement le mouvement panoramique : Multitouch.inputMode = MultitouchInputMode.GESTURE; stage.addEventListener(TransformGestureEvent.GESTURE_PAN , onPan); var myTextField = new TextField(); myTextField.y = 200; myTextField.text = "Perform a pan gesture"; addChild(myTextField); function onPan(evt:TransformGestureEvent):void { myTextField.text = "Pan is supported"; Les problèmes connus liés à la saisie tactile sont les suivants : 1 Mobile Internet Explorer sur un périphérique Windows Mobile effectue un zoom automatique sur un contenu issu
Pour résoudre ce problème de comportement de zoom dans Internet Explorer, ajoutez le code suivant à la page HTML qui héberge le fichier SWF : <head> <meta name="viewport" content="width=device-width, height=device-height, initialscale=1.0"> </head> • Retirez les doigts de l’écran. • Replacez les doigts sur l’écran et effectuez le mouvement de zoom. 3 Sous Windows 7 (et probablement sous d’autres systèmes d’exploitation), les mouvements de rotation et de zoom
4 Windows 7 Starter Edition ne gère pas la saisie multipoint. Pour plus d’informations, voir les forums d’Adobe
5 Sous Mac OS 10.5.3 et les versions ultérieures, la valeur Multitouch.supportsGestureEvents est toujours
Un objet Clipboard unique peut servir à rendre disponibles des représentations diverses des mêmes informations afin d’augmenter les possibilités des autres applications à comprendre et à utiliser ces données. Par exemple, une image pourrait être incluse en tant que données d’image, un objet Bitmap sérialisé et un fichier. Le rendu des données dans un format peut être reporté de telle sorte que celui-ci ne soit pas effectivement créé tant que les données de ce format ne sont pas lues.
Opération de copier-coller
Presse-papiers du système Flash Player 10 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour lire le contenu du Presse-papiers du système, appelez la méthode getData() de l’objet Clipboard.generalClipboard en lui communiquant le nom du format à lire : import flash.desktop.Clipboard; import flash.desktop.ClipboardFormats; if(Clipboard.generalClipboard.hasFormat(ClipboardFormats.TEXT_FORMAT)){ var text:String = Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT); }
Pour écrire dans le Presse-papiers, ajoutez les données à l’objet Clipboard.generalClipbooard dans un ou plusieurs formats. Toute donnée existante du même format est automatiquement écrasée. Toutefois, prenez l’habitude de vider le Presse-papiers du système avant de lui envoyer de nouvelles données. Vous vous assurez ainsi que les données superflues dans d’autres formats sont également supprimées. import flash.desktop.Clipboard; import flash.desktop.ClipboardFormats; var textToCopy:String = "Copy to clipboard."; Clipboard.generalClipboard.clear(); Clipboard.generalClipboard.setData(ClipboardFormats.TEXT_FORMAT, textToCopy, false);
événements copier-coller envoyé par un élément provenant d’un document HTML. Les événements copier-coller sont les suivants : copy, cut et paste. L’objet envoyé pour ces événements fournit un accès au Presse-papiers par la propriété clipboardData.
Adobe AIR 1.0 et les versions ultérieures Par défaut, AIR copie les éléments sélectionnées en réponse à la commande copier qui peut être engendrée soit par un raccourci-clavier, soit par un menu contextuel. Au sein des zones modifiables, AIR coupe du texte en réponse à des commandes couper ou bien colle du texte au curseur ou à la sélection en réponse à la commande coller. Pour éviter le comportement par défaut, votre gestionnaire d’événement peut appeler la méthode preventDefault() de l’objet événement envoyé.
Adobe AIR 1.0 et les versions ultérieures La propriété clipboardData de l’objet événement envoyé à la suite de l’un des événements copier-coller vous permet de lire des données du Presse-papiers et d’écrire dedans. Pour écrire dans le Presse-papiers lors de l’exécution d’un événement copier-coller, utilisez la méthode setData() de l’objet clipboardData en faisant passer les données à copier et le type de MIME : function customCopy(event){ event.clipboardData.setData("text/plain", "A copied string."); }
} L’exemple ci-dessous illustre la façon de remplacer le comportement copier-coller par défaut dans une page HTML. Le gestionnaire d’événement copy met en italiques le texte copié et le copie dans le Presse-papiers sous la forme de texte HTML. Le gestionnaire d’événement cut copie les données sélectionnées dans le Presse-papiers et les supprime du document. Le gestionnaire paste insère le contenu du Presse-papiers sous forme de HTML en caractères gras :
Dernière mise à jour le 27/4/2013
Les constantes qui définissent les noms des formats standard sont fournies par la classe ClipboardFormats : Constante
HTML hébergé dans une application AIR, il faut utiliser des types MIME à la place des chaînes ClipboardFormat. Les types MIME de données valides sont les suivants :
Vous pouvez utiliser des formats personnalisés définis dans les applications pour transférer des objets en tant que références ou des copies sérialisées. Les références ne sont valides que dans l’application d’origine. Les objets sérialisés peuvent être transférés entre applications, mais ne peuvent être utilisés qu’avec des objets qui demeurent valides lorsqu’ils sont sérialisés et désérialisés. Les objets peuvent généralement être sérialisés si leurs propriétés sont soit des types simples, soit des objets sérialisables. Pour ajouter un objet sérialisé à un objet Clipboard, définissez le paramètre serializable sur true lorsque vous appelez la méthode Clipboard.setData(). Le nom du format peut être celui d’un format standard ou une chaîne arbitraire définie par votre application.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lorsqu’un objet est écrit dans le Presse-papiers dans un format de données personnalisé, les données de l’objet peuvent être lues depuis le Presse-papiers soit comme une référence, soit comme une copie sérialisée de l’objet d’origine. Quatre modes de transfert déterminent si les objets sont transférés en tant que références ou en tant que copies sérialisées : Mode de transfert
Lors de l’écriture d’un objet dans le Presse-papiers, vous pouvez utiliser toute chaîne qui ne commence pas par les préfixes réservés air: ou flash: pour le paramètre format. Utilisez la même chaîne que le format pour lire l’objet. Les exemples suivants illustrent la façon de lire et d’écrire des objets dans le Presse-papiers. public function createClipboardObject(object:Object):Clipboard{ var transfer:Clipboard = Clipboard.generalClipboard; transfer.setData("object", object, true); }
Opération de copier-coller
ORIGINAL_PREFFERED pour accéder à la référence lorsqu’elle devient disponible et le clone sérialisé lorsque la référence ne l’est pas.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Si la création d’un format de données est coûteuse en ressources informatiques, vous pouvez procéder à un rendu différé en fournissant une fonction qui fournit les données à la demande. La fonction n’est appelée que si le récepteur de l’opération déposer ou coller demande les données dans le format différé. La fonction de rendu est ajoutée à l’objet Clipboard à l’aide de la méthodesetDataHandler(). La fonction doit renvoyer les données dans un format approprié. Par exemple, si vous appelez setDataHandler(ClipboardFormat.TEXT_FORMAT, writeText), alors la fonction writeText() doit renvoyer une chaîne. Si un format de données de même type est ajouté à l’objet Clipboard avec la méthode setData(), ces données priment sur la version différée (la fonction de rendu n’est jamais appelée). Selon le cas, la fonction de rendu peut être appelée à nouveau ou non si les mêmes données du Presse-papiers sont à nouveau utilisées. Remarque : sous Mac OS X, le rendu différé ne fonctionne qu’avec des formats de données personnalisés. Avec des formats de données standard, la fonction de rendu est appelée immédiatement.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’exemple ci-dessous illustre la façon d’implémenter une fonction de rendu. Lorsque l’utilisateur appuie sur le bouton Copier, l’application vide le Presse-papiers du système pour s’assurer qu’aucune donnée d’opérations de Presse-papiers précédentes ne subsiste. La méthode setDataHandler() définit alors la fonction renderData() comme rendu du Presse-papiers. Lorsque l’utilisateur choisit la commande Coller du menu contextuel du champ de texte de destination, l’application accède au Presse-papiers et définit le texte de destination. Comme le format des données texte du Presse-papiers a été défini avec une fonction plutôt qu’une chaîne, le Presse-papiers appelle la fonction renderData(). Cette fonction renderData() renvoie le texte dans le texte source qui, lui, est affecté au texte de destination. Notez que si vous éditez le texte source avant d’appuyer sur le bouton Coller, les modifications se retrouveront dans le texte collé, même lorsque l’édition survient après avoir appuyé sur le bouton Copier. Cette situation existe du fait que la fonction de rendu ne copie pas le texte source tant que l’on n’a pas appuyé sur le bouton Coller. Lorsque vous utilisez le rendu différé dans une véritable application, vous pourriez vouloir stocker ou protéger les données source de manière à éviter ce problème.
Les axes de l’accéléromètre sont normalisés par rapport à l’orientation de l’affichage, plutôt qu’à l’orientation physique du périphérique. Toute modification de l’orientation de l’affichage par le périphérique entraîne la réorientation en conséquence des axes de l’accéléromètre. Par conséquent, l’axe y est toujours plus ou moins vertical lorsque l’utilisateur tient le téléphone dans une position verticale standard, quelle que soit la direction de rotation du téléphone. Si l’orientation automatique est désactivée (lorsque le contenu SWF d’un navigateur est affiché en mode Plain écran, par exemple), les axes de l’accéléromètre ne sont pas réorientés lors de la rotation du périphérique.
La propriété Accelerometer.isSupported permet de vérifier si l’environnement d’exécution prend en charge cette fonction : if (Accelerometer.isSupported) { // Set up Accelerometer event listeners and code. } Accelerometer sur le périphérique de l’utilisateur. Si Accelerometer.isSupported est défini sur true à l’exécution, la prise en charge de la fonction Accelerometer est active.
Saisie via un accéléromètre
Pour utiliser le capteur de l’accéléromètre, instanciez un objet Accelerometer et enregistrez-vous pour recevoir les événements update qu’il distribue. Un événement update est un objet d’événement Accelerometer. L’événement possède quatre propriétés, toutes numériques :
L’accélération est négative si la face du périphérique est orientée vers le sol.
qui correspond à la fréquence de mise à jour requise, en millisecondes : var accl:Accelerometer; accl = new Accelerometer(); accl.setRequestedUpdateInterval(1000);
L’API glisser-déposer permet à un utilisateur de faire glisser des données d’une application à l’autre ou d’un composant d’application à l’autre. Parmi les formats de transfert pris en charge figurent :
• Fichiers Pour obtenir une explication rapide de l’utilisation des opérations glisser-déposer dans une application AIR et des exemples de code correspondants, voir les articles de démarrage rapide dans Adobe Developer Connection :
• Prise en charge des opérations glisser-déposer et copier-coller (Flash) L’API glisser-déposer contient les classes suivantes.
composant tout en maintenant enfoncé le bouton de la souris. Le composant source de l’élément glissé porte généralement le nom d’initiateur du glissement et distribue les événements nativeDragStart et nativeDragComplete. Une application Adobe AIR démarre une opération de glissement en appelant la méthode NativeDragManager.doDrag() en réponse à un événement mouseDown ou mouseMove. Si l’opération de glissement commence à l’extérieur d’une application AIR, aucun objet initiateur ne déclenche les événements nativeDragStart ou nativeDragComplete. Glissement Tout en maintenant enfoncé le bouton de la souris, l’utilisateur déplace le curseur vers un autre composant,
Le gestionnaire d’événement peut inspecter l’objet événement pour déterminer si les données glissées sont disponibles dans un format géré par la cible. Si tel est le cas, il autorise l’utilisateur à déposer les données sur la cible en appelant la méthode NativeDragManager.acceptDragDrop(). Tant que le mouvement de glissement survole un objet interactif, celui-ci distribue des événements nativeDragOver. Lorsque le mouvement de glissement quitte l’objet interactif, celui-ci distribue un événement nativeDragExit. Dépôt L’utilisateur relâche la souris sur une cible de dépôt appropriée. Si la cible est un composant ou une
La classe NativeDragManager contrôle les mouvements de glissement vers l’intérieur et l’extérieur. Tous les membres de la classe NativeDragManager étant statiques, ils ne créent pas d’occurrence de cette dernière.
Clipboard. Un objet Clipboard unique peut proposer plusieurs représentations des mêmes informations pour augmenter les chances qu’une autre application comprenne et utilise les données. Une image peut par exemple être incluse en tant que données d’image, objet Bitmap sérialisé ou fichier. Le rendu des données dans un format peut être confié à une fonction de rendu qui n’est pas appelée tant que les données n’ont pas été lues. Une fois le mouvement de glissement démarré, il n’est possible d’accéder à l’objet Clipboard qu’à partir d’un gestionnaire associé aux événements nativeDragEnter, nativeDragOver et nativeDragDrop. Lorsque le mouvement de glissement est terminé, l’objet Clipboard ne peut être ni lu ni réutilisé. Un objet application peut être transféré sous forme de référence et d’objet sérialisé. Les références sont valables uniquement dans leur application d’origine. Les transferts d’objets sérialisés sont valides d’une application AIR à une autre, mais sont réservés aux objets qui demeurent valides lorsqu’ils sont sérialisés et désérialisés. Les objets sérialisés sont convertis au format AMF3 (Action Message Format for ActionScript 3), qui permet de transférer des données sous forme de chaînes. Utilisation de la structure Flex Dans la plupart des cas, il est recommandé d’utiliser l’API glisser-déposer d’Adobe® Flex™ lors de la création d’applications Flex. La structure Flex propose un jeu de fonctions équivalentes lorsqu’une application Flex est exécutée dans AIR (elle utilise la classe NativeDragManager d’AIR en interne). Flex gère également un jeu plus limité de fonctions lorsqu’une application ou un composant s’exécute dans l’environnement plus restrictif d’un navigateur. Il est impossible d’utiliser les classes AIR dans des composants ou applications qui tournent en dehors de l’environnement d’exécution AIR.
Adobe AIR 1.0 et les versions ultérieures Pour prendre en charge le mouvement de glissement vers l’extérieur, vous devez créer un objet Clipboard en réponse à un événement mouseDown et l’envoyer à la méthode NativeDragManager.doDrag(). Votre application peut alors écouter l’événement nativeDragComplete sur l’objet initiateur pour déterminer la marche à suivre lorsque l’utilisateur termine ou abandonne le mouvement.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour préparer les données ou un objet à faire glisser, créez un objet Clipboard et ajoutez les informations à transférer dans un ou plusieurs formats. Vous disposez des formats de données standard pour transmettre des données susceptibles d’être converties automatiquement en formats Presse-papiers natifs, ainsi que des formats définis par l’application pour transmettre des objets. Si la conversion d’informations à transférer dans un format déterminé mobilise un volume élevé de ressources de calcul, vous pouvez indiquer le nom d’une fonction de gestionnaire qui exécutera la conversion. La fonction est appelée sous réserve que le composant ou l’application qui reçoit les données lise le format correspondant. Pour plus d’informations sur les formats du Presse-papiers, voir « Formats de données Clipboard » à la page 619.
événement mouse down. La méthode doDrag() est statique et gère les paramètres suivants : Paramètre
L’exemple charge une image et, lors d’un événement mouseDown, démarre l’opération de glissement.
Adobe AIR 1.0 et les versions ultérieures Pour prendre en charge le mouvement de glissement vers l’intérieur, votre application (ou, le plus souvent, un composant visuel de cette dernière) doit répondre aux événements nativeDragEnter ou nativeDragOver.
Adobe AIR 1.0 et les versions ultérieures La séquence d’événements suivante est caractéristique d’une opération de dépôt : 1 L’utilisateur fait glisser un objet Clipboard vers un composant. 2 Le composant distribue un événement nativeDragEnter.
4 NativeDragManager modifie le curseur de la souris pour indiquer que l’objet peut être déposé. 5 L’utilisateur dépose l’objet sur le composant. 6 Le composant cible distribue un événement nativeDragDrop. 7 Le composant cible lit les données au format approprié à partir de l’objet Clipboard au sein de l’objet événement. 8 Si le mouvement de glissement a débuté dans une application AIR, l’objet initiateur interactif distribue un
Adobe AIR 1.0 et les versions ultérieures Lorsqu’un utilisateur fait glisser un élément Clipboard vers les limites d’un composant visuel, celui-ci distribue les événements nativeDragEnter et nativeDragOver. Pour déterminer si le composant peut accepter l’élément Clipboard, les gestionnaires de ces événements peuvent vérifier les propriétés clipboard et allowedActions de l’objet événement. Pour signaler que le composant peut accepter le dépôt, le gestionnaire d’événement doit appeler la méthode NativeDragManager.acceptDragDrop() et transmettre une référence au composant récepteur. Si plusieurs écouteurs d’événement enregistrés appellent la méthode acceptDragDrop(), le dernier gestionnaire de la liste prime. L’appel acceptDragDrop() demeure valide jusqu’à ce que la souris quitte les limites de l’objet qui accepte l’élément, déclenchant ainsi l’événement nativeDragExit. Si plusieurs actions sont autorisées par le paramètre allowedActions transmis à doDrag(), l’utilisateur peut indiquer l’action autorisée qu’il souhaite exécuter en maintenant enfoncée une touche de modification. Le gestionnaire de glissement modifie l’image associée au curseur pour indiquer à l’utilisateur l’action qui se produirait s’il achevait le dépôt. L’action prévue est signalée par la propriété dropAction de l’objet NativeDragEvent. L’action associée à un mouvement de glissement est définie à titre indicatif uniquement. Les composants impliqués dans le transfert doivent mettre en œuvre le comportement approprié. Pour achever une action de déplacement, par exemple, l’initiateur du glissement peut supprimer l’élément glissé et la cible du dépôt peut l’ajouter. La cible du glissement peut limiter l’action de dépôt à l’une des trois actions gérées en définissant la propriété dropAction de la classe NativeDragManager. Si un utilisateur tente de sélectionner une autre action par le biais du clavier, NativeDragManager affiche le curseur unavailable. Définissez la propriété dropAction des gestionnaires associés aux événements nativeDragEnter et nativeDragOver. L’exemple suivant illustre un gestionnaire associé à l’événement nativeDragEnter ou nativeDragOver. Ce gestionnaire accepte un mouvement de glissement vers l’intérieur sous réserve que l’objet Clipboard en cours de glissement contienne des données au format texte. import flash.desktop.NativeDragManager; import flash.events.NativeDragEvent; public function onDragIn(event:NativeDragEvent):void{ NativeDragManager.dropAction = NativeDragActions.MOVE; if(event.clipboard.hasFormat(ClipboardFormats.TEXT_FORMAT)){ NativeDragManager.acceptDragDrop(this); //'this' is the receiving component } Lorsque l’utilisateur dépose un élément glissé sur un objet interactif qui a accepté le mouvement, ce dernier distribue un événement nativeDragDrop. Le gestionnaire de cet événement peut extraire les données de la propriété clipboard de l’objet événement. Si la propriété clipboard contient un format défini par l’application, le paramètre transferMode transmis à la méthode getData() de l’objet Clipboard détermine si le gestionnaire de glissement renvoie une référence ou une version sérialisée de l’objet. L’exemple suivant illustre un gestionnaire associé à l’événement nativeDragDrop : import flash.desktop.Clipboard; import flash.events.NativeDragEvent; public function onDrop(event:NativeDragEvent):void { if (event.clipboard.hasFormat(ClipboardFormats.TEXT_FORMAT)) { var text:String = String(event.clipboard.getData(ClipboardFormats.TEXT_FORMAT, ClipboardTransferMode.ORIGINAL_PREFERRED)); Un composant peut mettre à jour son apparence visuelle en fonction des événements NativeDragEvent. Le tableau cidessous décrit les types de modifications effectuées par un composant standard en réponse à divers événements : Evénement
Si un mouvement de glissement survole un composant, ce dernier distribue des événements nativeDragOver. Ces événements sont distribués toutes les quelques millisecondes, ainsi qu’à chaque déplacement de la souris. L’objet événement nativeDragOver permet également de déterminer la position de la souris au-dessus du composant. Connaître la position de la souris peut s’avérer utile dans des circonstances où le composant récepteur est complexe, mais ne possède pas de sous-composants. Par exemple, si votre application a affiché une image bitmap contenant une carte de rue et que vous souhaitez mettre en évidence les zones de la carte dans lesquelles l’utilisateur a fait glisser des informations, vous pouvez utiliser les coordonnées de la souris indiquées par l’événement nativeDragOver pour assurer le suivi de la position de la souris au sein de la carte.
Pour faire glisser des données vers une application HTML ou hors de cette dernière (ou vers le code HTML affiché dans un objet HTMLLoader et hors de ce dernier), vous disposez des événements glisser-déposer HTML. L’API glisser-déposer HTML vous permet de faire glisser des données vers des éléments DOM ou à partir de ces derniers dans le contenu HTML. Remarque : vous pouvez également utiliser les API NativeDragEvent et NativeDragManager d’AIR en écoutant les événements sur l’objet HTMLLoader qui comporte le contenu HTML. L’API HTML est toutefois mieux intégrée au DOM HTML et permet de contrôler le comportement par défaut.
Adobe AIR 1.0 et les versions ultérieures L’environnement HTML définit le comportement par défaut des actions glisser-déposer qui impliquent du texte, des images et des URL. Le comportement par défaut permet de faire glisser ces types de données hors d’un élément. Vous ne pouvez toutefois faire glisser que du texte vers un élément, sous réserve qu’il réside dans une zone modifiable de page. Lorsque vous faites glisser du texte entre des zones modifiables d’une page ou au sein de l’une de ces zones, le comportement par défaut consiste à exécuter une action de déplacement. Lorsque vous faites glisser du texte vers une zone modifiable à partir d’une zone non modifiable ou de l’extérieur de l’application, le comportement par défaut consiste à exécuter une action de copie. Vous pouvez remplacer le comportement par défaut en gérant vous-même les événements glisser-déposer. Pour annuler le comportement par défaut, vous devez appeler les méthodes preventDefault() des objets distribués suite aux événements glisser-déposer. Vous pouvez ensuite insérer des données dans la cible du dépôt et supprimer les données de la source du glissement pour exécuter l’action sélectionnée.
Par exemple, si vous définissez -webkit-user-select sur none, il est impossible de sélectionner les contenus d’élément et, par conséquent, de les faire glisser. La propriété CSS -webkit-user-drag permet également de déterminer s’il est possible de faire glisser un élément global. Le contenu de l’élément est toutefois traité séparément. L’utilisateur peut néanmoins faire glisser une section sélectionnée de texte. Pour plus d’informations, voir « CSS dans AIR » à la page 1015.
Les événements distribués par l’élément initiateur à l’origine d’un glissement sont indiqués dans le tableau suivant : Evénement
La principale propriété d’un objet événement drag correspond à dataTransfer, qui contient les données en cours de glissement. L’objet dataTransfer en tant que tel dispose des propriétés et méthodes suivantes :
Effets de glissement dans HTML Adobe AIR 1.0 et les versions ultérieures L’initiateur du mouvement de glissement peut limiter les effets de glissement autorisés en définissant la propriété dataTransfer.effectAllowed du gestionnaire de l’événement dragstart. Les valeurs de chaîne suivantes sont prises en charge : Valeur de chaîne
Pour indiquer les effets de glissement pris en charge par un objet source lorsque vous ne vous fondez pas sur le comportement par défaut, définissez la propriété dataTransfer.effectAllowed de l’objet distribué pour l’événement dragstart. Vous disposez de n’importe quelle combinaison d’effets. Par exemple, si un élément source prend en charge les effets copy et link, définissez la propriété sur copyLink.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Ajoutez les données associées au mouvement de glissement dans le gestionnaire de l’événement dragstart par le biais de la propriété dataTransfer. La méthode dataTransfer.setData() permet de placer les données dans le Pressepapiers en transmettant le type MIME et les données à transférer. Par exemple, si votre application contient un élément image doté de l’identifiant imageOfGeorge, vous pouvez utiliser le gestionnaire d’événement dragstart suivant. Cet exemple ajoute des représentations d’une photo de George en plusieurs formats de données, augmentant ainsi les chances d’utilisation des données glissées par d’autres applications. function dragStartHandler(event){ event.dataTransfer.effectAllowed = "copy"; var dragImage = document.getElementById("imageOfGeorge"); var dragFile = new air.File(dragImage.src); event.dataTransfer.setData("text/plain","A picture of George"); event.dataTransfer.setData("image/x-vnd.adobe.air.bitmap", dragImage); event.dataTransfer.setData("application/x-vnd.adobe.air.file-list", new Array(dragFile)); }
Le comportement par défaut n’autorise que le glissement de texte vers des zones modifiables de la page. Vous pouvez indiquer qu’un élément et ses enfants peuvent devenir modifiables en incluant l’attribut contenteditable dans la balise de début de l’élément. Vous pouvez également rendre un document entier modifiable en définissant la propriété designMode de l’objet Document sur on.
Pour gérer le mouvement de glissement vers l’intérieur, vous devez au préalable annuler le comportement par défaut. Ecoutez les événements dragenter et dragover sur tout élément HTML à utiliser à titre de cible de dépôt. Dans les gestionnaires de ces événements, appelez la méthode preventDefault() de l’objet événement distribué. Annuler le comportement par défaut permet aux zones non modifiables de recevoir un dépôt.
Adobe AIR 1.0 et les versions ultérieures Vous pouvez accéder aux données déposées dans le gestionnaire de l’événement ondrop : function doDrop(event){ droppedText = event.dataTransfer.getData("text/plain"); }
MIME du format de données à lire. Pour identifier les formats de données disponibles, utilisez la propriété types de l’objet dataTransfer. Le tableau types contient la chaîne de type MIME de chaque format disponible. Lorsque vous annulez le comportement par défaut pour les événements dragenter ou dragover, il vous incombe d’insérer toute donnée déposée à l’emplacement approprié dans le document. Il n’existe pas d’API permettant de convertir une position souris en point d’insertion au sein d’un élément. Cette restriction risque de compliquer la mise en œuvre des mouvements de glissement de type insertion.
Adobe AIR 1.0 et les versions ultérieures Cet exemple met en œuvre une cible de dépôt qui affiche un tableau contenant tous les formats de données disponibles dans l’élément déposé. Le comportement par défaut permet d’autoriser le glissement du texte, des liens et des images au sein de l’application. L’exemple remplace le comportement de glissement vers l’intérieur par défaut de l’élément div faisant office de cible du dépôt. La principale étape du processus d’activation du contenu non modifiable de sorte à accepter un mouvement de glissement vers l’intérieur consiste à appeler la méthode preventDefault() de l’objet événement distribué pour les événements dragenter et dragover. En réponse à un événement drop, le gestionnaire convertit les données transférées en élément row HTML et insère la ligne dans un tableau pour l’afficher.
Un contenu hors application ne peut pas accepter les objets File qui résultent d’un glissement des fichiers vers une application AIR. Il est également impossible de transmettre l’un de ces objets File à un contenu d’application via un pont de sandbox. (Il est nécessaire d’accéder aux propriétés d’objet pendant la sérialisation.) Vous pouvez toutefois continuer à déposer des fichiers dans votre application en écoutant les événements nativeDragDrop AIR de l’objet HTMLLoader. En temps normal, si un utilisateur dépose un fichier dans un cadre qui héberge un contenu hors application, l’événement dépôt n’est pas propagé de l’enfant au parent. Toutefois, puisque les événements distribués par l’objet HTMLLoader (qui comporte tous les contenus HTML d’une application AIR) ne sont pas intégrés au flux d’événement HTML, vous pouvez continuer à recevoir l’événement dépôt dans un contenu d’application. Pour recevoir l’événement associé à un dépôt de fichier, le document parent ajoute un écouteur d’événement à l’objet HTMLLoader par le biais de la référence fournie par window.htmlLoader : window.htmlLoader.addEventListener("nativeDragDrop",function(event){ var filelist = event.clipboard.getData(air.ClipboardFormats.FILE_LIST_FORMAT); air.trace(filelist[0].url); });
(définie dans le package flash.desktop du moteur d’exécution). D’un point de vue conceptuel, les fichiers promis sont similaires à un rendu différé qui fait appel à une fonction de gestion des données du Presse-papiers. Utilisez les fichiers promis au lieu d’un rendu différé lorsque vous glissezdéposez des fichiers. La technique de rendu différé entraîne parfois des pauses indésirables du mouvement de glissement lors de la génération ou du téléchargement des données. Faites appel au rendu différé pour les opérations de copie et de collage, qui ne prennent pas en charge les fichiers promis. Restrictions associées à l’utilisation de fichiers promis Par rapport aux autres formats de données gérés par un Presse-papiers de type glisser-déposer, les fichiers promis sont soumis aux restrictions suivantes :
Clipboard.supportsFilePromise permet de vérifier si les fichiers promis sont pris en charge sur le système hôte.
(Clipboard.generalClipboard).
URLFilePromise, vous pouvez implémenter l’interface IFilePromise dans une classe personnalisée. L’interface IFilePromise définit les méthodes et propriétés utilisées par le moteur d’exécution AIR pour accéder aux données à écrire dans un fichier une fois le fichier promis déposé.
AIR peut lire les données en mode synchrone et asynchrone. L’implémentation d’IFilePromise indique le mode d’accès pris en charge en renvoyant la valeur correspondante dans la propriété isAsync. Si un accès asynchrone aux données est proposé, l’objet fournisseur de données doit implémenter l’interface IEventDispatcher et distribuer les événements requis, tels que open, progress et complete. Vous pouvez utiliser une classe personnalisée ou l’une des classes intégrées suivantes en tant que fournisseur de données associé à un fichier promis :
• FileStream (accès synchrone ou asynchrone) Toutes les méthodes IFilePromise sont appelées par le moteur d’exécution dans le cadre d’une opération de glisserdéposer qui concerne le fichier promis. En règle générale, la logique de l’application ne devrait pas appeler directement ces méthodes.
Adobe AIR 2 et ultérieur La technique d’implémentation de l’interface IFilePromise la plus simple consiste à utiliser un objet fournisseur de données synchrone tel que ByteArray ou un objet FileStream synchrone. Dans l’exemple suivant, un objet ByteArray est créé, rempli de données et renvoyé lorsque la méthode open() est appelée.
événements socketData sont distribués par les objets Socket. Le moteur d’exécution écoute les événements appropriés qui émanent de tous ces objets. Les événements suivants étayent le processus de lecture des données à partir de l’objet fournisseur de données :
• ProgressEvent.PROGRESS — Indique au moteur d’exécution que les données sont disponibles. Le moteur d’exécution lit le volume de données disponibles dans l’objet fournisseur de données.
• Event.CLOSE — Indique au moteur d’exécution que la lecture des données est terminée. (A ce titre, le moteur d’exécution écoute les événements close et complete.)
Le fournisseur de données doit distribuer ces événements dans l’ordre suivant : 1 événement open 2 événements progress ou socketData 3 événement complete ou close Dernière mise à jour le 27/4/2013
Les classes de l’API de menus natifs permettent de définir des menus en incrustation, contextuels, de fenêtre et d’application dans Adobe® AIR®.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour obtenir une explication rapide de la création de menus natifs dans une application AIR et des exemples de code, voir les articles de démarrage rapide suivants dans Adobe Developer Connection :
• Ajout de menus natifs à une application AIR (Flash) Les classes de menus natifs vous permettent d’accéder aux fonctions de menu natif du système d’exploitation sur lequel s’exécute votre application. Des objets NativeMenu peuvent être utilisés pour les menus d’application (sous Mac OS X), les menus de fenêtre (sous Windows et Linux), les menus contextuels et les menus en incrustation. En dehors d’AIR, vous disposez des classes de menus contextuels pour modifier le menu contextuel automatiquement affiché par Flash Player lorsqu’un utilisateur clique avec le bouton droit de la souris ou en maintenant la touche Commande enfoncée sur un objet de votre application. (Aucun menu contextuel automatique ne s’affiche pour les applications AIR.)
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les classes de menus sont les suivantes : Package
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures AIR prend en charge les types de menus suivants : Menus contextuels Un menu contextuel s’affiche lorsque l’utilisateur clique avec le bouton droit de la souris ou en maintenant la touche Commande enfoncée sur un objet interactif dans du contenu SWF ou sur un élément de document dans du contenu HTML.
ContextMenu et ContextMenuItem pour ajouter vos propres commandes au menu. Vous pouvez également supprimer certaines des commandes intégrées, mais pas toutes. Dans le moteur d’exécution AIR, vous pouvez créer un menu contextuel à l’aide de la classe NativeMenu ou ContextMenu. Un contenu HTML dans AIR vous permet d’utiliser les API Webkit HTML et JavaScript pour ajouter des menus contextuels aux éléments HTML. Menus d’application (AIR uniquement) Un menu d’application est un menu global qui s’applique à la totalité de
Mac OS x, le système d’exploitation crée automatiquement un menu d’application. Vous pouvez utiliser l’API de menus d’AIR pour ajouter des éléments et des sous-menus aux menus standard. Vous pouvez ajouter des écouteurs pour gérer les commandes de menu existantes et vous pouvez supprimer des éléments existants. Menus de fenêtre (AIR uniquement) Un menu de fenêtre est associé à une fenêtre unique et s’affiche sous la barre de titre. Pour ajouter des menus à une fenêtre, vous créez un objet NativeMenu et l’affectez à la propriété menu de l’objet NativeWindow. Les menus de fenêtre sont pris en charge par les systèmes d’exploitation Windows et Linux, mais pas par Mac OS X. Les menus de fenêtre natifs ne peuvent être utilisés qu’avec les fenêtres disposant d’un chrome système. Menus d’icônes de la barre d’état système et du Dock (AIR uniquement) Similaires aux menus contextuels, les menus
NativeMenu. Sous Mac OS X, les éléments du menu sont ajoutés au-dessus des éléments standard du système d’exploitation. Sous Windows et Linux, le menu standard n’existe pas. Menus en incrustation (AIR uniquement) Un menu en incrustation AIR est similaire à un menu contextuel mais il
Menus personnalisés Les menus natifs sont dessinés entièrement par le système d’exploitation et, en tant que tels, existent en dehors des modèles de rendu Flash et HTML. Au lieu d’utiliser des menus natifs, vous pouvez créer des menus personnalisés non natifs à l’aide de MXML, ActionScript, ou JavaScript (dans AIR). Les menus de ce type doivent s’afficher complètement dans le contenu d’une application. Menus Flex La structure Adobe® Flex™ propose un ensemble de composants de menu Flex. Les menus Flex sont
Menus par défaut (AIR uniquement) Les menus par défaut suivants sont proposés par le système d’exploitation ou une classe AIR intégrée :
• Menu contextuel associé au texte sélectionné dans un objet TextField (ou un objet étendant TextField)
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Dans du contenu SWF, il est possible d’associer un menu contextuel à tout objet qui hérite des propriétés ou méthodes de InteractiveObject en affectant un objet menu à sa propriété contextMenu. Plusieurs commandes sont incluses par défaut, notamment des commandes d’avance, de recul, d’impression, de qualité et de zoom. Dans le moteur d’exécution AIR, l’objet menu affecté à contextMenu peut être de type NativeMenu ou ContextMenu. Dans le moteur d’exécution Flash Player, seule la classe ContextMenu est disponible. Vous pouvez écouter les événements des menus natifs ou des menus contextuels lorsque vous utilisez les classes ContextMenu et ContextMenuItem ; les deux sont distribués. L’un des avantages des propriétés de l’objet ContextMenuEvent est que contextMenuOwner identifie l’objet auquel le menu est associé et mouseTarget identifie l’objet sur lequel l’utilisateur a cliqué pour ouvrir le menu. Ces informations ne sont pas disponibles avec l’objet NativeMenuEvent. L’exemple suivant crée un sprite et l’ajoute à un menu contextuel edit simple : var sprite:Sprite = new Sprite(); sprite.contextMenu = createContextMenu() private function createContextMenu():ContextMenu{ var editContextMenu:ContextMenu = new ContextMenu(); var cutItem:ContextMenuItem = new ContextMenuItem("Cut") cutItem.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT, doCutCommand); editContextMenu.customItems.push(cutItem); var copyItem:ContextMenuItem = new ContextMenuItem("Copy") copyItem.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT, doCopyCommand); editContextMenu.customItems.push(copyItem); var pasteItem:ContextMenuItem = new ContextMenuItem("Paste") pasteItem.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT, doPasteCommand); editContextMenu.customItems.push(pasteItem); return editContextMenu } private function doCutCommand(event:ContextMenuEvent):void{trace("cut");} private function doCopyCommand(event:ContextMenuEvent):void{trace("copy");} private function doPasteCommand(event:ContextMenuEvent):void{trace("paste");} Dernière mise à jour le 27/4/2013
ContextMenu, appelez la méthode hideBuiltInItems() et affectez cette occurrence à la propriété contextMenu de cette occurrence de DisplayObject. L’exemple suivant crée un carré dessiné dynamiquement avec une commande de menu contextuel qui permet de modifier sa couleur au hasard : var square:Sprite = new Sprite(); square.graphics.beginFill(0x000000); square.graphics.drawRect(0,0,100,100); square.graphics.endFill(); square.x = square.y = 10; addChild(square); var menuItem:ContextMenuItem = new ContextMenuItem("Change Color"); menuItem.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT,changeColor); var customContextMenu:ContextMenu = new ContextMenu(); customContextMenu.hideBuiltInItems(); customContextMenu.customItems.push(menuItem); square.contextMenu = customContextMenu; function changeColor(event:ContextMenuEvent):void { square.transform.colorTransform = getRandomColor(); } function getRandomColor():ColorTransform { return new ColorTransform(Math.random(), Math.random(), Math.random(),1,(Math.random() * NativeMenuItem. Les objets NativeMenuItem qui représentent des sous-menus peuvent eux aussi contenir des objets NativeMenu. L’objet menu du niveau supérieur ou racine de la structure représente la barre de menus des menus d’application et de fenêtre. (Les menus contextuels, d’icônes et en incrustation ne possèdent pas de barre de menus.)
NativeMenu sert de conteneur des éléments du sous-menu. Par le biais de sa propriété submenu, l’objet NativeMenuItem référence l’objet NativeMenu. Vous trouverez un exemple de code qui crée ce menu à la section « Exemple de menu natif : menu de fenêtre et d’application (AIR) » à la page 666.
Adobe AIR 1.0 et les versions ultérieures Les objets NativeMenu et NativeMenuItem distribuent tous deux des événements preparing, displaying, et select : Preparing : lorsque l’objet est sur le point de démarrer une interaction utilisateur, le menu et les sous-menus correspondants distribuent un événement preparing à tout écouteur enregistré. Parmi les interactions figurent l’ouverture du menu et la sélection d’une option par le biais d’un raccourci clavier.
Displaying : juste avant son affichage, un menu et ses options distribuent un événement displaying à tout écouteur
Les événements preparing et displaying permettent de mettre à jour le contenu du menu ou l’apparence de l’option avant son affichage à l’intention de l’utilisateur. Par exemple, dans l’écouteur de l’événement displaying d’un menu « Ouvrir un fichier récent », vous pourriez modifier les options de menu en fonction de la liste actuelle de documents affichés récemment. Si vous supprimez l’option de menu dont le raccourci clavier a déclenché un événement preparing, l’interaction de menu est annulée et aucun événement select n’est distribué. Les propriétés target et currentTarget de l’événement correspondent toutes deux à l’objet auquel est associé l’écouteur, c’est-à-dire au menu en tant que tel ou à l’une de ses options. L’événement preparing est distribué avant l’événement displaying. Vous écoutez généralement l’un des deux événements, mais non les deux à la fois. Sélection : lorsque l’utilisateur choisit une commande, l’élément distribue un événement select à tout écouteur enregistré. Les sous-menus ou les séparateurs ne distribuent jamais d’événements select car il est impossible de les sélectionner.
Remarque : les objets ContextMenu et ContextMenuItem distribuent des événements menuItemSelect et menuSelect, ainsi que des événements select, preparing et displaying.
Adobe AIR 1.0 et les versions ultérieures Vous pouvez affecter un équivalent clavier (parfois appelé accélérateur) à une commande de menu. L’élément de menu distribue un événement select à tout écouteur enregistré lorsque l’utilisateur appuie sur la touche ou la combinaison de touches. Le menu contenant l’élément doit appartenir au menu de l’application ou de la fenêtre active pour la commande à appeler. L’équivalent clavier se compose de deux parties : une chaîne représentant la touche principale et un tableau de touches de modification sur lesquelles il est également nécessaire d’appuyer. Pour affecter une touche principale, définissez la propriété keyEquivalent de l’élément de menu sur la chaîne à caractère unique correspondant à cette touche. Si vous utilisez une majuscule, la touche Maj est automatiquement ajoutée au tableau de touches de modification. Sous Mac OS X, la touche Commande (Keyboard.COMMAND) est la touche de modification par défaut. Sous Windows et Linux, il s’agit de la touche Ctrl (Keyboard.CONTROL). Ces touches par défaut sont automatiquement ajoutées au tableau de touches de modification. Pour utiliser d’autres touches de modification, affectez un nouveau tableau contenant les codes de touche souhaités à la propriété keyEquivalentModifiers. Le tableau par défaut est remplacé. Que vous utilisiez les touches de modification par défaut ou votre propre tableau de touches de modification, la touche Maj est ajoutée si la chaîne que vous affectez à la propriété keyEquivalent est une lettre majuscule. Les constantes correspondant aux codes de touche à utiliser pour les touches de modification sont définies dans la classe Keyboard. La chaîne d’équivalent clavier affectée est automatiquement affichée en regard du nom de l’élément de menu. Le format varie selon le système d’exploitation et les préférences système de l’utilisateur.
équivalent clavier n’est affiché dans le menu. En revanche, il est impératif d’utiliser la touche Ctrl pour activer la commande de menu. L’exemple suivant affecte l’équivalent clavier Ctrl+Maj+G à un élément de menu : var item:NativeMenuItem = new NativeMenuItem("Ungroup"); item.keyEquivalent = "G";
Sous Mac OS X, l’utilisateur saisit la ou les deux premières lettres du menu ou de la commande et appuie sur Entrée. La propriété mnemonicIndex est ignorée. Sous Windows, seule une lettre est significative. Par défaut, elle correspond au premier caractère du libellé mais si vous affectez une mnémonique à un élément de menu, la lettre désignée devient le caractère significatif. Si deux éléments d’un menu possèdent le même caractère significatif (qu’une mnémonique ait été affectée ou non), l’interaction avec le menu à partir du clavier change légèrement. Plutôt que d’appuyer sur une seule lettre pour sélectionner le menu ou la commande, l’utilisateur appuie sur la lettre autant de fois que nécessaire pour mettre en évidence l’élément souhaité, puis il appuie sur la touche Entrée pour confirmer la sélection. Pour garantir un comportement cohérent, il est préférable d’affecter une seule mnémonique à chaque élément d’un menu sous Windows. Sous Linux, aucune mnémonique n’est fournie par défaut. Pour fournir une mnémonique, vous devez définir la valeur de la propriété mnemonicIndex d’un élément de menu. Spécifiez le caractère mnémonique en tant qu’index dans la chaîne de libellé. L’index du premier caractère d’un libellé est 0. Ainsi pour utiliser le « r » comme mnémonique d’un menu intitulé « Format », vous définissez la propriété mnemonicIndex sur 2. var item:NativeMenuItem = new NativeMenuItem("Format"); item.mnemonicIndex = 2;
Adobe AIR 1.0 et les versions ultérieures Les éléments de menu possèdent deux propriétés d’état : checked (coché) et enabled (activé) : checked Définissez cette propriété sur true pour afficher une coche en regard du libellé de l’élément.
La propriété data de la classe NativeMenuItem vous permet de référencer un objet arbitraire dans chaque élément. Par exemple, dans un menu « Ouvrir un fichier récent », vous pourriez affecter l’objet File associé à chaque document à chaque élément de menu. var file:File = File.applicationStorageDirectory.resolvePath("GreatGatsby.pdf") var menuItem:NativeMenuItem = docMenu.addItem(new NativeMenuItem(file.name)); menuItem.data = file;
Adobe AIR 1.0 et les versions ultérieures Cette rubrique explique comment créer les différents types de menus natifs pris en charge par AIR.
Adobe AIR 1.0 et les versions ultérieures Pour créer un objet NativeMenu en tant que racine du menu, utilisez le constructeur NativeMenu : var root:NativeMenu = new NativeMenu();
Une fois le menu créé, vous pouvez lui ajouter des éléments de menu. Les éléments figurent dans le menu dans l’ordre dans lequel vous les ajoutez, à moins que vous ne les ajoutiez à un index spécifique à l’aide de la méthode addItemAt() d’un objet menu. Affectez le menu en tant que menu d’application, de fenêtre, d’icône ou contextuel ou affichez-le en tant que menu en incrustation, comme indiqué dans les sections suivantes : Définition d’un menu d’application ou de fenêtre Le code doit prendre en charge à la fois les menus d’application (gérés sous Mac OS) et les menus de fenêtre (gérés sous d’autres systèmes d’exploitation).
NativeMenu définissant le sous-menu sur la propriété submenu de l’élément. AIR vous propose deux méthodes de création des éléments de sous-menu et de l’objet menu associé : Vous pouvez créer un élément de menu et son objet menu associé en une seule opération à l’aide de la méthode addSubmenu() :
Pour créer une commande de menu, ajoutez un objet NativeMenuItem à un menu et ajoutez un écouteur d’événement référençant la fonction qui met en œuvre la commande de menu : var copy:NativeMenuItem = new NativeMenuItem("Copy", false); copy.addEventListener(Event.SELECT, onCopyCommand); editMenu.addItem(copy);
Remarque : les éléments de menu qui représentent des sous-menus et des séparateurs ne distribuent pas d’événements select et vous ne pouvez donc pas les utiliser en tant que commandes.
Adobe AIR 1.0 et les versions ultérieures Pour créer un séparateur, créez un objet NativeMenuItem, en définissant le paramètre isSeparator sur true dans le constructeur. Ajoutez ensuite le séparateur au menu à l’emplacement approprié : var separatorA:NativeMenuItem = new NativeMenuItem("A", true); editMenu.addItem(separatorA);
(AIR) Adobe AIR 1.0 et les versions ultérieures Dans un contenu HTML affiché à l’aide de l’objet HTMLLoader, l’événement contextmenu permet d’afficher un menu contextuel. Par défaut, un menu contextuel est affiché automatiquement lorsque l’utilisateur appelle l’événement contextmenu sur le texte sélectionné (en cliquant avec le bouton droit de la souris ou en cliquant tout en appuyant sur la touche Commande). Pour empêcher l’affichage du menu par défaut, écoutez l’événement contextmenu et appelez la méthode preventDefault() de l’objet événement : function showContextMenu(event){ event.preventDefault(); }
Vous pouvez afficher tout objet NativeMenu à tout moment et à tout emplacement au-dessus d’une fenêtre en appelant la méthode display() du menu. Cette méthode exigeant une référence à la scène, seul le contenu figurant dans le sandbox de l’application peut afficher un menu en incrustation. La méthode suivante affiche le menu défini par l’objet NativeMenu popupMenu en réponse à un clic de souris : private function onMouseClick(event:MouseEvent):void { popupMenu.display(event.target.stage, event.stageX, event.stageY); }
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Un menu distribue des événements lorsque l’utilisateur sélectionne le menu ou l’un de ses éléments.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Ajoutez des écouteurs d’événement à des menus ou à des éléments individuels pour gérer les événements de menu. Object
Comme les événements select remontent jusqu’aux menus conteneur, vous pouvez aussi les écouter sur un menu parent. Lorsque vous écoutez au niveau d’un menu, vous pouvez utiliser la propriété target de l’objet événement pour déterminer la commande de menu sélectionnée. L’exemple suivant suit la trace du libellé de la commande sélectionnée :
Adobe AIR 1.0 et les versions ultérieures Pour gérer l’ouverture d’un menu, vous pouvez ajouter un événement displaying, qui est distribué avant l’affichage d’un menu. L’événement displaying permet de mettre à jour le menu, par exemple en ajoutant ou supprimant des éléments, ou en actualisant l’état, activé ou coché, d’éléments individuels. Vous pouvez également écouter l’événement menuSelect à partir d’un objet ContextMenu. Dans AIR 2.6 et les versions ultérieures, vous disposez de l’événement preparing pour mettre à jour un menu en réponse à l’affichage d’un menu ou à la sélection d’une option par le biais d’un raccourci clavier.
Adobe AIR 1.0 et les versions ultérieures L'exemple suivant crée le menu affiché à la section « Structure de menu natif (AIR) » à la page 657.
Si NativeWindow.supportsMenu est défini sur true, le constructeur crée un objet NativeMenu pour la fenêtre, puis crée et ajoute les sous-menus File et Edit. Si NativeApplication.supportsMenu est défini sur true, le constructeur crée les menus File et Edit, et les ajoute au menu existant que propose le système d’exploitation Mac OS X. L’exemple suivant illustre également la gestion des événements de menu. L’événement select est géré au niveau des éléments et au niveau du menu. Chaque menu du chaînage allant du menu contenant l’élément sélectionné au menu racine répond à l’événement select. L’événement displaying est utilisé avec le menu « Ouvrir un fichier récent ». Juste avant l’ouverture du menu, ses éléments sont actualisés à partir du tableau recentDocuments (qui, dans cet exemple, reste inchangé). Bien que cette procédure ne soit pas illustrée dans cet exemple, vous pouvez également écouter des événements displaying sur des éléments individuels. package { import import import import import import import
• Utilisation des icônes de la barre d’état système et du Dock (Flash)
Adobe AIR 1.0 et les versions ultérieures AIR crée l’objet NativeApplication.nativeApplication.icon automatiquement. Selon le système d’exploitation, le type d’objet est soit DockIcon soit SystemTrayIcon. Les propriétés NativeApplication.supportsDockIcon et NativeApplication.supportsSystemTrayIcon vous permettent de déterminer les sous-classes InteractiveIcon prises en charge par AIR sur le système d’exploitation actuel. La classe de base InteractiveIcon fournit les propriétés width, height et bitmaps, qui vous permettent de modifier l’image utilisée pour l’icône. En revanche, l’accès aux propriétés spécifiques à l’objet DockIcon ou SystemTrayIcon sur le mauvais système d’exploitation génère une erreur d’exécution. Pour définir ou modifier l’image utilisée pour une icône, créez un tableau contenant une ou plusieurs images, puis affectez-le à la propriété NativeApplication.nativeApplication.icon.bitmaps. La taille des icônes de la barre des tâches peut varier d’un système d’exploitation à l’autre. Pour éviter la dégradation de l’image provoquée par la mise à l’échelle, vous pouvez ajouter plusieurs tailles d’image au tableau bitmaps. Si vous fournissez plusieurs images, AIR sélectionne la taille la plus proche de la taille d’affichage actuelle de l’icône de la barre des tâches et, le cas échéant, met ces images à l’échelle. Dans l’exemple suivant, l’image d’une icône de la barre des tâches est définie à l’aide de deux images : NativeApplication.nativeApplication.icon.bitmaps = [bmp16x16.bitmapData, bmp128x128.bitmapData];
Vous pouvez animer l’icône en modifiant l’image en réponse à un événement enterFrame ou timer.
NativeApplication.nativeApplication.icon.bitmaps = [];
Adobe AIR 1.0 et les versions ultérieures AIR prend en charge les icônes du Dock lorsque la propriété NativeApplication.supportsDockIcon est définie sur true. La propriété NativeApplication.nativeApplication.icon représente l’icône de l’application sur le Dock (et non l’icône de la fenêtre). Remarque : AIR ne permet pas de modifier les icônes de fenêtre sur le Dock sous Mac OS X. Par ailleurs, les modifications apportées à l’icône du Dock de l’application ne sont appliquées que lorsqu’une application est en cours d’exécution ; l’icône retrouve son aspect normal lorsque vous quittez l’application.
Adobe AIR 1.0 et les versions ultérieures Vous pouvez ajouter des commandes au menu du Dock standard en créant un objet NativeMenu contenant les commandes, puis en l’affectant à la propriété NativeApplication.nativeApplication.icon.menu. Les éléments du menu s’affichent au-dessus des options de menu de l’icône du Dock standard.
Adobe AIR 1.0 et les versions ultérieures Vous pouvez faire rebondir l’icône du Dock en appelant la méthode NativeApplication.nativeApplication.icon.bounce(). Si vous définissez le paramètre bounce() priority sur informational, l’icône rebondit une fois. Si vous définissez ce paramètre sur critical, l’icône rebondit jusqu’à ce que l’utilisateur active l’application. Les constantes du paramètre priority sont définies dans la classe NotificationType. Remarque : l’icône ne rebondit pas si l’application est déjà active.
Adobe AIR 1.0 et les versions ultérieures Lorsque vous cliquez sur l’icône du Dock, l’objet NativeApplication distribue un événement invoke. Si l’application n’est pas en cours d’exécution, le système lance l’application. Sinon, l’événement invoke est renvoyé à l’occurrence de l’application en cours d’exécution.
AIR prend en charge les icônes de la barre d’état système lorsque la propriété NativeApplication.supportsSystemTrayIcon est définie sur true, ce qui n’est actuellement le cas que sous Windows et la plupart des distributions Linux. Sous Windows et Linux, les icônes de la barre d’état système s’affichent dans la zone de notification de la barre des tâches. Par défaut, aucune icône n’est affichée. Pour afficher une icône, affectez un tableau contenant des objets BitmapData à la propriété bitmaps de l’icône. Pour modifier l’image d’une icône, affectez un tableau contenant les nouvelles images à la propriété bitmaps. Pour supprimer l’icône, définissez la propriété bitmaps sur null.
Adobe AIR 1.0 et les versions ultérieures Vous pouvez ajouter un menu à l’icône de la barre d’état système en créant un objet NativeMenu, puis en l’affectant à la propriété NativeApplication.nativeApplication.icon.menu (le système d’exploitation ne fournit aucun menu par défaut). Pour accéder au menu de l’icône de la barre d’état système, cliquez sur l’icône avec le bouton droit de la souris.
Adobe AIR 1.0 et les versions ultérieures Pour ajouter une info-bulle à une icône, définissez la propriété tooltip : NativeApplication.nativeApplication.icon.tooltip = "Application name";
Adobe AIR 1.0 et les versions ultérieures L’objet SystemTrayIcon référencé par la propriété NativeApplication.nativeApplication.icon distribue un événement ScreenMouseEvent pour les événements click, mouseDown, mouseUp, rightClick, rightMouseDown et rightMouseUp. Vous pouvez utiliser ces événements, ainsi que le menu d’une icône, pour autoriser les utilisateurs à interagir avec votre application lorsque celle-ci ne dispose pas de fenêtres visibles.
Adobe AIR 1.0 et les versions ultérieures L’exemple suivant crée une application AIR qui dispose d’une icône de la barre d’état système, mais d’aucune fenêtre visible. (Ne définissez pas la propriété visible de l’application sur true dans le descripteur d’application, sous peine que la fenêtre ne soit visible au démarrage de l’application.)
Icônes et boutons de la barre des tâches de la fenêtre Adobe AIR 1.0 et les versions ultérieures Les icônes des fenêtres s’affichent normalement dans une zone de la fenêtre, appelée barre des tâches ou Dock, pour permettre aux utilisateurs d’accéder aisément à l’arrière-plan ou aux fenêtre minimisées. Le Dock de Mac OS X affiche l’icône correspondant à votre application, ainsi qu’une icône pour chaque fenêtre minimisée. Les barres des tâches de Microsoft Windows et Linux affichent un bouton contenant l’icône et le titre du programme de chaque fenêtre standard dans votre application.
Adobe AIR 1.0 et les versions ultérieures Lorsqu’une fenêtre se trouve dans le chrome, vous pouvez informer l’utilisateur qu’un événement important ayant trait à la fenêtre s’est produit. Sous Mac OS X, vous pouvez informer l’utilisateur en faisant rebondir l’icône de l’application du Dock (comme décrit à la section « Rebond de l’icône du Dock » à la page 671). Sous Windows et Linux, vous pouvez mettre en surbrillance le bouton de la barre des tâches de la fenêtre en appelant la méthode notifyUser() de l’occurrence de NativeWindow. Le paramètre type transmis à la méthode détermine l’urgence de la notification :
L’instruction suivante met en surbrillance le bouton de la barre des tâches d’une fenêtre : stage.nativeWindow.notifyUser(NotificationType.CRITICAL);
Adobe AIR 1.0 et les versions ultérieures Sous Windows, les fenêtres de type utilitaire ou légère ne s’affichent pas dans la barre des tâches. Les fenêtres invisibles n’apparaissent pas non plus dans la barre des tâches.
Dans les nouvelles fenêtres ouvertes par l’application, définissez la propriété type de l’objet NativeWindowInitOption transmis au constructeur de fenêtres sur NativeWindowType.UTILITY ou sur NativeWindowType.LIGHTWEIGHT. Sous Mac OS X, les fenêtres minimisées apparaissent sur la barre des tâches du Dock. Vous pouvez désactiver l’affichage de l’icône minimisée en masquant la fenêtre au lieu de la minimiser. L’exemple suivant écoute un événement de changement nativeWindowDisplayState et l’annule si la fenêtre est minimisée. Le gestionnaire définit la propriété visible de la fenêtre sur false : private function preventMinimize(event:NativeWindowDisplayStateEvent):void{ if(event.afterDisplayState == NativeWindowDisplayState.MINIMIZED){ event.preventDefault(); event.target.visible = false; } }
Flash® Player propose des fonctionnalités de lecture et d’écriture de fichier de base, par le biais de la classe FileReference. Pour des raisons de sécurité, l’utilisateur doit systématiquement accorder son autorisation pour que vous puissiez lire ou écrire un fichier dans Flash Player. Adobe® AIR® assure un accès plus complet au système de fichiers de l’ordinateur hôte que Flash Player. L’API du système de fichiers AIR vous permet d’accéder aux fichiers et aux répertoires et de les gérer, de créer des fichiers et des répertoires, d’écrire des données dans les fichiers, etc.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Un objet FileReference représente un fichier de données stocké sur un client ou un serveur. Les méthodes de la classe FileReference permettent à votre application de charger et d’enregistrer localement des fichiers de données et de transférer ces derniers entre la machine locale et un serveur distant. La classe FileReference propose deux approches distinctes pour charger, transférer et enregistrer les fichiers de données. Depuis son introduction, la classe FileReference comprend les méthodes browse(), upload() et download(). La méthode browse() permet à l’utilisateur de sélectionner un fichier. La méthode upload() permet de transférer les données du fichier vers un serveur distant. La méthode download() permet d’extraire les données du serveur et de les enregistrer dans un fichier local. Depuis Flash Player 10 et Adobe AIR 1.5, la classe FileReference intègre les méthodes load() et save(). Grâce aux méthodes load() et save(), vous pouvez également accéder aux fichiers locaux et les enregistrer directement. L’utilisation de ces méthodes est similaire aux méthodes du même nom dont disposent les classes URLLoader et Loader. Remarque : la classe File, qui étend la classe FileReference, et la classe FileStream proposent d’autres fonctions de manipulation des fichiers et du système de fichiers local. Les classes File et FileStream sont prises en charge dans AIR uniquement et non dans Flash Player.
Utilisation du système de fichiers
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Chaque objet FileReference représente un fichier de données local hébergé sur la machine locale. Les propriétés de la classe FileReference contiennent des informations sur la taille, le type, le nom, l’extension, le créateur, la date de création et la date de modification du fichier. Remarque : la propriété creator est prise en charge sous Mac OS uniquement. Toutes les autres plates-formes renvoient la valeur null. Remarque : la propriété extension est prise en charge par Adobe AIR uniquement. Pour créer une occurrence de la classe FileReference, procédez comme suit, au choix :
Une fois l’objet FileReference créé, vous pouvez procéder comme suit :
FileReference.upload() charge le fichier sur un serveur distant. La méthode FileReference.load() ouvre un fichier local.
à l’utilisateur de sélectionner l’emplacement d’enregistrement d’un nouveau fichier. Elle télécharge ensuite les données du serveur et les stocke dans le nouveau fichier.
Remarque : vous ne pouvez exécuter qu’une seule méthode browse(), download() ou save() à la fois, car une seule boîte de dialogue peut être ouverte à un moment donné. Les propriétés de l’objet FileReference, telles que name, size ou modificationDate, ne sont pas définies tant que l’un des événements suivants ne s’est pas produit :
Remarque : lors d’un téléchargement, seule la propriété FileReference.name est renseignée avant la fin du téléchargement. Une fois que le fichier est téléchargé, toutes les propriétés sont disponibles.
FileReference.download(), FileReference.load() ou FileReference.save(), la plupart des lecteurs poursuivent la lecture du fichier SWF, ainsi que la distribution d’événements et l’exécution du code. Pour les opérations de chargement ou téléchargement, un fichier SWF peut uniquement accéder aux fichiers de son propre domaine, ce qui comprend tous les domaines spécifiés par un fichier de régulation. Vous devez placer un fichier de régulation sur le serveur contenant le fichier, si ce serveur ne se trouve pas sur le même domaine que le fichier SWF ayant initié le chargement ou le téléchargement. Voir FileReference.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La méthode FileReference.load() vous permet de charger des données en mémoire à partir d’un fichier local. Remarque : le code doit tout d’abord appeler la méthode FileReference.browse() pour que l’utilisateur puisse sélectionner le fichier à charger. Cette restriction ne s’applique pas au contenu qui s’exécute dans le sandbox de sécurité de l’application Adobe AIR. La méthode FileReference.load() renvoie une valeur immédiatement après avoir été appelée, mais les données en cours de chargement ne sont pas disponibles tout de suite. L’objet FileReference distribue des événements pour appeler les méthodes d’écouteur à chaque étape du processus de chargement. L’objet FileReference distribue les événements suivants pendant le processus de chargement.
• Evénement progress (ProgressEvent.PROGRESS) : distribué régulièrement lorsque le fichier lit des octets de données.
• Evénement ioError (IOErrorEvent.IO_ERROR) : distribué si le processus de chargement échoue en raison d’une erreur d’entrée/sortie lors de l’ouverture ou de la lecture des données du fichier. Une fois que l’objet FileReference distribue l’événement complete, il est possible d’accéder aux données chargées comme un élément ByteArray dans la propriété data de l’objet FileReference. L’exemple suivant indique comment inviter l’utilisateur à sélectionner un fichier, puis à charger les données de ce dernier en mémoire :
Lorsque le chargement est terminé, l’application affiche le contenu du fichier chargé à l’aide de la méthode trace(). Dans Adobe AIR, la classe FileStream propose d’autres fonctionnalités de lecture des données dans un fichier local (voir « Lecture et écriture de fichiers » à la page 715).
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La méthode FileReference.save() vous permet d’enregistrer des données dans un fichier local. Elle commence par ouvrir une boîte de dialogue qui permet à l’utilisateur d’entrer un nouveau nom de fichier et l’emplacement d’enregistrement du fichier. Une fois le nom de fichier et l’emplacement sélectionnés, les données sont écrites dans le nouveau fichier. Lorsque le fichier est enregistré, les propriétés de l’objet FileReference sont renseignées avec les propriétés du fichier local. Remarque : le code ne doit appeler la méthode FileReference.save() qu’en réponse à un événement utilisateur, tel qu’un événement de type clic de souris ou pression de touche. Dans le cas contraire, une erreur est renvoyée. Cette restriction ne s’applique pas au contenu qui s’exécute dans le sandbox de sécurité de l’application Adobe AIR. La méthode FileReference.save() est renvoyée juste après son appel. L’objet FileReference distribue ensuite des événements pour appeler les méthodes d’écouteur à chaque étape du processus d’enregistrement de fichier. L’objet FileReference distribue les événements suivants au cours du processus d’enregistrement de fichier :
• Evénement progress (ProgressEvent.PROGRESS) : distribué régulièrement pendant l’enregistrement des octets de données dans le fichier.
• S’il s’agit d’un objet XML, elles sont écrites dans un fichier XML en conservant l’ensemble du formatage. • S’il s’agit d’un objet ByteArray, leur contenu est écrit directement dans le fichier sans conversion. • S’il s’agit d’un autre type d’objet, la méthode FileReference.save() appelle la méthode toString() de l’objet, puis enregistre la valeur String résultante dans un fichier texte UTF-8. S’il est impossible d’appeler la méthode toString() de l’objet, une erreur est renvoyée. Si la valeur du paramètre data est null, une erreur est renvoyée.
Dans Adobe AIR, la classe FileStream propose d’autres fonctionnalités d’écriture des données dans un fichier local (voir « Lecture et écriture de fichiers » à la page 715).
Chargement de fichiers sur un serveur Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour charger des fichiers sur un serveur, commencez par appeler la méthode browse() pour permettre à l’utilisateur de sélectionner un ou plusieurs fichiers. Après l’appel de la méthode FileReference.upload(), le fichier sélectionné est transféré sur le serveur. Si l’utilisateur sélectionne plusieurs fichiers à l’aide de la méthode FileReferenceList.browse(), Flash Player crée un tableau de fichiers sélectionnés appelé FileReferenceList.fileList. Vous pouvez alors utiliser la méthode FileReference.upload() pour charger chaque fichier individuellement. Remarque : l’utilisation de la méthode FileReference.browse() ne vous permet de charger qu’un seul fichier à la fois. Pour autoriser l’utilisateur à charger plusieurs fichiers, faites appel à la méthode FileReferenceList.browse(). Par défaut, la boîte de dialogue de sélection de fichier du système d’exploitation permet à l’utilisateur de choisir tout type de fichier sur l’ordinateur local. Les développeurs peuvent toutefois filtrer les types de fichier à l’aide de la classe FileFilter, en transmettant un tableau d’occurrences de filtres de fichiers à la méthode browse() : var imageTypes:FileFilter = new FileFilter("Images (*.jpg, *.jpeg, *.gif, *.png)", "*.jpg; *.jpeg; *.gif; *.png"); var textTypes:FileFilter = new FileFilter("Text Files (*.txt, *.rtf)", "*.txt; *.rtf"); var allTypes:Array = new Array(imageTypes, textTypes); var fileRef:FileReference = new FileReference(); fileRef.browse(allTypes);
FileReference.browse(), le code suivant envoie le fichier à un serveur Web : var fileRef:FileReference = new FileReference(); fileRef.addEventListener(Event.SELECT, selectHandler); fileRef.addEventListener(Event.COMPLETE, completeHandler); try { var success:Boolean = fileRef.browse(); } catch (error:Error) { trace("Unable to browse for files."); Avec la méthode FileReference.upload(), vous pouvez envoyer des données au serveur en utilisant les propriétés URLRequest.method et URLRequest.data en vue d’envoyer des variables à l’aide de la méthode POST ou GET. Si vous tentez de charger un fichier à l’aide de la méthode FileReference.upload(), les événements suivants sont distribués :
• Evénement progress (ProgressEvent.PROGRESS) : distribué régulièrement pendant le chargement des octets de données du fichier.
• Evénement httpStatus (HTTPStatusEvent.HTTP_STATUS) : distribué lorsque le processus de chargement échoue en raison d’une erreur HTTP.
Flash Player n’offre pas une prise en charge complète des serveurs nécessitant une authentification. Seuls les fichiers SWF s’exécutant dans un navigateur, via le module d’extension du navigateur ou le contrôle Microsoft ActiveX®, peuvent fournir une boîte de dialogue pour inviter l’utilisateur à entrer un nom et un mot de passe d’authentification, et ce uniquement pour les téléchargements. Le transfert de fichiers échoue si le chargement est effectué à l’aide du module d’extension ou du contrôle ActiveX, ou si un chargement/téléchargement est effectué par le biais du lecteur autonome ou externe. Pour créer un script serveur dans ColdFusion de manière à accepter les chargements de fichier en provenance de Flash Player, vous pouvez utiliser un code semblable à celui-ci : <cffile action="upload" filefield="Filedata" destination="#ExpandPath('./')#" nameconflict="OVERWRITE" />
ColdFusion, en écrasant tout fichier existant du même nom. Cet exemple présente le minimum de code nécessaire à l’acceptation du chargement d’un fichier ; ce script ne doit pas être utilisé dans un environnement de production. Ajoutez de préférence un mécanisme de validation des données pour garantir que les utilisateurs chargent uniquement des types de fichiers autorisés, telle une image plutôt qu’un script côté serveur potentiellement dangereux.
ActionScript 3.0 vous permet de remplacer le nom de champ par défaut du fichier à charger (Filedata) en ajoutant un deuxième paramètre à la méthode upload(), comme illustré dans l’exemple précédent (dans lequel la valeur par défaut Filedata est remplacée par Custom1). Par défaut, Flash Player ne tente pas d’effectuer un chargement de test ; vous pouvez toutefois le faire en transmettant la valeur true comme troisième paramètre de la méthode upload(). L’objectif du test est de vérifier que le chargement véritable se fera sans problème et que l’authentification du serveur, si nécessaire, réussira. Remarque : actuellement, le test du chargement s’effectue uniquement dans les versions Windows de Flash Player. Le script serveur qui gère le chargement doit attendre une requête HTTP POST comportant les éléments suivants :
FileReference.download(), qui prend deux paramètres : request et defaultFileName. Le premier paramètre est l’objet URLRequest contenant l’URL du fichier à télécharger. Le second est facultatif ; il permet de spécifier un nom de fichier par défaut qui apparaîtra dans la boîte de dialogue de téléchargement. Si vous ignorez le second paramètre, defaultFileName, le nom de fichier utilisé est dérivé de l’URL. Le code suivant télécharge un fichier nommé index.xml à partir du même répertoire que le fichier SWF : var request:URLRequest = new URLRequest("index.xml"); var fileRef:FileReference = new FileReference(); fileRef.download(request);
La classe FileReferenceList permet à l’utilisateur de sélectionner un ou plusieurs fichiers à charger dans un script côté serveur. Le chargement de fichiers est géré par la méthode FileReference.upload(), qui doit être appelée pour chaque fichier sélectionné. Le code suivant crée deux objets FileFilter (imageFilter et textFilter) et les transmet sous forme de tableau à la méthode FileReferenceList.browse(). Ainsi, la boîte de dialogue du système d’exploitation propose deux types de fichiers possibles. var imageFilter:FileFilter = new FileFilter("Image Files (*.jpg, *.jpeg, *.gif, *.png)", "*.jpg; *.jpeg; *.gif; *.png"); var textFilter:FileFilter = new FileFilter("Text Files (*.txt, *.rtf)", "*.txt; *.rtf"); var fileRefList:FileReferenceList = new FileReferenceList(); try { var success:Boolean = fileRefList.browse(new Array(imageFilter, textFilter)); } catch (error:Error) FileReference.upload(), comme le montre le code suivant :
• Obtenir des informations sur les fichiers et les répertoires • Lire et écrire des fichiers
Pour obtenir une explication rapide de l’utilisation du système de fichiers dans AIR et des exemples de code correspondants, voir les articles de démarrage rapide suivants dans Adobe Developer Connection :
• Développement d’un éditeur de fichier texte (Flex) • Développement d’une application de recherche dans des répertoires (Flex) • Lecture et écriture à partir d’un fichier de préférences XML (Flex) • Compression de fichiers et de données (Flex) Adobe AIR propose des classes permettant de créer et de gérer des fichiers et des dossiers, ainsi que d’y accéder. Ces classes, qui résident dans le package flash.filesystem, s’utilisent comme suit : Classes File
Les versions asynchrones vous permettent d’initier des processus s’exécutant en arrière-plan et de distribuer des événements lorsqu’ils sont terminés (ou lorsqu’un événement erreur se produit). Un autre code peut s’exécuter pendant que ces processus asynchrones se déroulent en arrière-plan. Lorsque vous utilisez la version asynchrone de ces opérations, vous devez configurer des fonctions d’écouteur d’événement, à l’aide de la méthode addEventListener() de l’objet File ou FileStream qui appelle la fonction. Les versions synchrones permettent d’écrire du code plus simple qui ne repose pas sur la configuration d’écouteurs d’événement. Cependant, comme aucun autre code ne peut s’exécuter pendant l’exécution d’une méthode synchrone, il est possible que des processus importants tels que l’animation et le rendu des objets d’affichage soient retardés.
Un objet File est un pointeur vers un fichier ou un répertoire du système de fichiers. La classe File étend la classe FileReference. La classe FileReference, qui est disponible dans Adobe® Flash® Player et AIR, représente un pointeur vers un fichier. La classe File ajoute des propriétés et des méthodes qui ne sont pas exposées dans Flash Player (dans un fichier SWF s’exécutant dans un navigateur), pour des raisons de sécurité.
Adobe AIR 1.0 et les versions ultérieures La classe File permet d’effectuer les opérations suivantes :
• Déplacer des fichiers et des répertoires • Supprimer des fichiers et des répertoires (ou les transférer dans la corbeille) • Afficher la liste des fichiers et répertoires que contient un répertoire • Créer des fichiers et des dossiers temporaires Une fois qu’un objet File pointe vers un chemin de fichier, vous pouvez l’utiliser pour lire et écrire des données de fichier, à l’aide de la classe FileStream. Un objet File peut pointer vers le chemin d’un fichier ou d’un répertoire qui n’existe pas encore. Vous pouvez utiliser un tel objet File pour créer un fichier ou un répertoire.
Adobe AIR 1.0 et les versions ultérieures Tout objet File possède deux propriétés qui définissent son chemin : Propriété
Parmi ces propriétés figurent :
Sur certains systèmes d’exploitation, l’application est stockée dans un fichier de package unique, plutôt que dans un répertoire physique. Dans ce cas de figure, il est parfois impossible d’accéder au contenu via le chemin natif. Le répertoire d’application est disponible en lecture seule.
Remarque : si une plate-forme ne définit pas d’emplacement standard pour les répertoires de poste de travail, de documents ou d’utilisateur, File.documentsDirectory, File.desktopDirectory et File.userDirectory peuvent pointer vers le même répertoire. La valeur de ces propriétés varie selon le système d’exploitation. Par exemple, le chemin natif vers le répertoire du poste de travail de l’utilisateur est différent sur Mac et Windows. La propriété File.desktopDirectory pointe néanmoins vers un chemin de répertoire approprié sur chaque plate-forme. Pour développer des applications qui fonctionnent correctement sur toutes les plateformes, utilisez ces propriétés comme base pour référencer d’autres fichiers et répertoires dont se sert l’application. Utilisez ensuite la méthode resolvePath() pour affiner le chemin. Par exemple, le code suivant pointe vers le fichier preferences.xml dans le répertoire de stockage de l’application : var prefsFile:File = File.applicationStorageDirectory; prefsFile = prefsFile.resolvePath("preferences.xml");
File.documentsDirectory.
Vous disposez de plusieurs méthodes pour configurer un objet File afin qu’il pointe vers un répertoire. Pointage vers le répertoire d’accueil de l’utilisateur Adobe AIR 1.0 et les versions ultérieures Vous pouvez pointer un objet File vers le répertoire d’accueil de l’utilisateur. Le code suivant configure l’objet File afin qu’il pointe vers le sous-répertoire AIR Test du répertoire d’accueil : var file:File = File.userDirectory.resolvePath("AIR Test");
Adobe AIR 1.0 et les versions ultérieures Vous pouvez pointer un objet File vers le répertoire de documents de l’utilisateur. Le code suivant configure un objet File afin qu’il pointe vers le sous-répertoire AIR Test du répertoire de documents : var file:File = File.documentsDirectory.resolvePath("AIR Test");
Adobe AIR 1.0 et les versions ultérieures Vous pouvez pointer un objet File vers le poste de travail. Le code suivant configure un objet File afin qu’il pointe vers le sous-répertoire AIR Test du poste de travail : var file:File = File.desktopDirectory.resolvePath("AIR Test");
Adobe AIR 1.0 et les versions ultérieures Vous pouvez pointer un objet File vers le répertoire de stockage d’une application. A toute application AIR est associé un chemin unique qui définit son répertoire de stockage. Ce répertoire est spécifique à chaque application et utilisateur. Vous pouvez y stocker des données spécifiques à l’application et à l’utilisateur, notamment des données utilisateur ou des fichiers de préférences. Par exemple, le code suivant pointe un objet File vers un fichier de préférences, prefs.xml, qui réside dans le répertoire de stockage de l’application : var file:File = File.applicationStorageDirectory; file = file.resolvePath("prefs.xml");
AIR 3.2 et versions antérieures : /Utilisateurs/nom utilisateur/Bibliothèque/Préférences/applicationID/Local Store/
(voir « Modèles d’URL AIR pris en charge » à la page 702), comme l’illustre l’exemple suivant : var dir:File = File.applicationDirectory; dir = dir.resolvePath("images"); trace(dir.url); // app:/images
La propriété nativePath est une chaîne vide. Accédez toujours aux fichiers que contient le répertoire de l’application par le biais de l’URL, plutôt que d’un chemin natif. Pointage vers le répertoire du cache Adobe AIR 3.6 et les versions ultérieures Vous pouvez pointer un objet File vers le répertoire temporaire ou de cache du système d’exploitation en utilisant la propriété File.cacheDirectory. Ce répertoire contient des fichiers temporaires qui ne sont pas nécessaires à l’exécution de l’application et dont la suppression ne cause pas de problèmes ni de pertes de données pour l’utilisateur. Dans la plupart des systèmes d’exploitation, le répertoire de cache est un répertoire temporaire. Sous iOS, le répertoire de cache correspond au répertoire Caches de la bibliothèque d’applications. Les fichiers de ce répertoire ne sont pas sauvegardés sur le stockage en ligne et peuvent être supprimés par le système d’exploitation si l’espace de stockage disponible sur le périphérique est insuffisant. Pour plus d’informations, voir « Contrôle de la sauvegarde et de la mise en cache des fichiers » à la page 702. Pointage vers la racine du système de fichiers Adobe AIR 1.0 et les versions ultérieures La méthode File.getRootDirectories() répertorie tous les volumes racine, tels que C: et les volumes montés, sur un ordinateur Windows. Sous Mac et Linux, cette méthode renvoie le répertoire racine unique de l’ordinateur (le répertoire « / »). La méthode StorageVolumeInfo.getStorageVolumes() propose des informations plus détaillées sur les volumes de stockage montés (voir « Utilisation des volumes de stockage » à la page 713). Remarque : il est impossible d’accéder en lecture à la racine du système de fichiers sur Android. La méthode renvoie un objet File qui pointe vers le répertoire par le biais du chemin natif « / », mais les propriétés de cet objet n’ont pas de valeur précise. Par exemple, spaceAvailable correspond toujours à 0.
Adobe AIR 1.0 et les versions ultérieures Vous pouvez pointer l’objet File vers un répertoire explicite en définissant sa propriété nativePath, comme l’illustre l’exemple ci-dessous (sous Windows) : var file:File = new File(); file.nativePath = "C:\\AIR Test";
Navigation vers des chemins relatifs Adobe AIR 1.0 et les versions ultérieures La méthode resolvePath() permet d’obtenir un chemin relatif à un autre chemin donné. Par exemple, le code suivant configure un objet File afin qu’il pointe vers le sous-répertoire « AIR Test » du répertoire d’accueil de l’utilisateur : var file:File = File.userDirectory; file = file.resolvePath("AIR Test");
Sélection d’un répertoire par l’utilisateur Adobe AIR 1.0 et les versions ultérieures La classe File comprend la méthode browseForDirectory(), qui présente une boîte de dialogue système dans laquelle l’utilisateur peut sélectionner un répertoire à affecter à l’objet. La méthode browseForDirectory() est asynchrone. L’objet File distribue un événement select si l’utilisateur sélectionne un répertoire et clique sur le bouton Ouvrir, ou un événement cancel si l’utilisateur clique sur le bouton Annuler. Par exemple, le code suivant permet à l’utilisateur de sélectionner un répertoire et renvoie le chemin de celui-ci une fois la sélection effectuée : var file:File = new File(); file.addEventListener(Event.SELECT, dirSelected); file.browseForDirectory("Select a directory"); function dirSelected(e:Event):void { trace(file.nativePath); }
Adobe AIR 1.0 et les versions ultérieures Vous pouvez déterminer l’emplacement du répertoire à partir duquel une application est appelée en consultant la propriété currentDirectory de l’objet InvokeEvent distribué lors de l’appel de l’application. Pour plus d’informations, voir la section « Capture des arguments de ligne de commande » à la page 912.
Adobe AIR 1.0 et les versions ultérieures Il existe plusieurs manières de définir le fichier vers lequel pointe un objet File. Pointage vers un chemin de fichier explicite Adobe AIR 1.0 et les versions ultérieures Important : pointer vers un chemin explicite risque de générer un code qui ne fonctionne pas sur toutes les platesformes. Ainsi, le chemin C:/foo.txt ne fonctionne que sous Windows. Les propriétés statiques de l’objet File, telles que File.applicationStorageDirectory, permettent de localiser un répertoire qui fonctionne sur toutes les platesformes. Utilisez ensuite la méthode resolvePath() (voir « Modification de chemins de fichier » à la page 702) pour accéder à un chemin relatif. La propriété url d’un objet File permet de pointer celui-ci vers un fichier ou un répertoire basé sur une chaîne d’URL, comme illustré ci-dessous : var urlStr:String = "file:///C:/AIR Test/test.txt"; var file:File = new File() file.url = urlStr;
Adobe AIR 1.0 et les versions ultérieures La méthode getDirectoryListing() d’un objet File permet d’obtenir un tableau d’objets File pointant vers les fichiers et sous-répertoires situés au niveau racine d’un répertoire. Pour plus d’informations, voir la section « Enumération de répertoires » à la page 709. Sélection d’un fichier par l’utilisateur Adobe AIR 1.0 et les versions ultérieures La classe File comprend les méthodes suivantes, qui présentent une boîte de dialogue système dans laquelle l’utilisateur peut sélectionner un fichier à affecter à l’objet :
Adobe AIR 1.0 et les versions ultérieures Vous pouvez également modifier le chemin d’un objet File existant en appelant la méthode resolvePath() ou en intervenant sur la propriété nativePath ou url de l’objet, comme l’illustrent les exemples suivants (sous Windows) : var file1:File = File.documentsDirectory; file1 = file1.resolvePath("AIR Test"); trace(file1.nativePath); // C:\Documents and Settings\userName\My Documents\AIR Test var file2:File = File.documentsDirectory; file2 = file2.resolvePath(".."); trace(file2.nativePath); // C:\Documents and Settings\userName var file3:File = File.documentsDirectory; file3.nativePath += "/subdirectory"; trace(file3.nativePath); // C:\Documents and Settings\userName\My Documents\subdirectory var file4:File = new File(); file4.url = "file:///c:/AIR Test/test.txt"; trace(file4.nativePath); // C:\AIR Test\test.txt
Adobe AIR 1.0 et les versions ultérieures Lorsque vous définissez la propriété url d’un objet File dans AIR, vous pouvez utiliser les modèles d’URL suivants :
Certains systèmes d’exploitation, notamment iOS et Mac OS X, offrent aux utilisateurs la possibilité de sauvegarder automatiquement les fichiers d’application sur un serveur de stockage distant. En outre, iOS présente des restrictions concernant la sauvegarde des fichiers et l’emplacement de stockage des différents types de fichier.
• Pour spécifier qu’un fichier n’a pas besoin d’être sauvegardé et (iOS uniquement) peut être supprimé par le système d’exploitation si le périphérique manque d’espace de stockage, enregistrez le ficher dans le répertoire de cache (File.cacheDirectory). Il s’agit de l’emplacement de stockage par défaut sous iOS, et il doit être utilisé pour la plupart des fichiers qui peuvent être régénérés ou retéléchargés.
(File.documentsDirectory). Définissez la propriété preventBackup de l’objet File sur true. Apple demande de procéder de cette manière pour tout contenu qu’il est possible de générer ou télécharger à nouveau, mais qui est nécessaire au bon fonctionnement de votre application lors d’une utilisation hors ligne. Spécification des fichiers à sauvegarder Afin d’économiser l’espace de sauvegarde et de réduire le trafic réseau, les directives d’Apple pour les applications iOS et Mac spécifient que seuls les fichiers contenant des données saisies par l’utilisateur ou des données qu’il n’est pas possible de générer ou de télécharger à nouveau doivent être marqués comme « à sauvegarder ». Par défaut, tous les fichiers des dossiers de la bibliothèque d’applications sont sauvegardés. Sous Mac OS X, il s’agit du répertoire de stockage des applications. Sous iOS, cela inclut le répertoire de stockage de l’application, le répertoire d’application, le répertoire Bureau, le répertoire de documents et le répertoire de l’utilisateur (car ces répertoires sont mappés sur les dossiers de la bibliothèque d’applications sur iOS). Par conséquent, tous les fichiers de ces répertoires sont sauvegardés par défaut sur serveur de stockage. Si vous enregistrez dans l’un de ces emplacements un fichier que votre application peut recréer, il est recommandé de lui appliquer un marqueur de sorte que le système d’exploitation ne le sauvegarde pas. Pour indiquer qu’un fichier ne doit pas être sauvegardé, définissez la propriété preventBackup de l’objet File sur true. Remarque : sous iOS, tout fichier se trouvant dans l’un des dossiers de la bibliothèque d’applications (même si sa propriété preventBackup a la valeur true) est marqué comme un fichier persistant que le système d’exploitation ne doit pas supprimer. Contrôle de la mise en cache et de la suppression des fichiers Les directives d’Apple concernant les applications iOS spécifient que, dans la mesure du possible, tout contenu qu’il est possible de régénérer doit pouvoir être supprimé par le système d’exploitation si l’espace de stockage est insuffisant sur le périphérique. Sous iOS, les fichiers des dossiers de la bibliothèque d’applications (comme le répertoire de stockage de l’application ou le répertoire de documents) sont marqués comme permanents et ne sont pas supprimés par le système d’exploitation. Enregistrez les fichiers que l’application peut régénérer et qui peuvent être supprimés sans risque si l’espace de stockage est insuffisant dans le répertoire de cache de l’application. Pour accéder au répertoire de cache, utilisez la propriété statique File.cacheDirectory. Sous iOS, le répertoire de cache correspond au répertoire de cache de l’application (<Racine de l’application>/Library/Caches). Sous d’autres systèmes d’exploitation, ce répertoire est mappé sur un répertoire comparable. Par exemple, sous Mac OS X, il est également mappé sur le répertoire Caches de la bibliothèque d’applications. Sous Android, le répertoire de cache est mappé sur le répertoire de cache de l’application. Sous Windows, le répertoire de cache est mappé sur le répertoire temp du système d’exploitation. Sous Android et sous Windows, il s’agit du même répertoire que celui auquel accède un appel aux méthodes createTempDirectory() et createTempFile() de la classe File.
Les noms de fichier et de chemin ne respectent pas la casse sous Windows et Mac OS. Dans l’exemple suivant, deux objets File pointent vers un même fichier : File.documentsDirectory.resolvePath("test.txt"); File.documentsDirectory.resolvePath("TeSt.TxT");
Adobe AIR 1.0 et les versions ultérieures Divers systèmes d’exploitation prennent en charge les fichiers de package et les fichiers de lien symbolique : Packages—Sous Mac OS, les répertoires peuvent être désignés comme packages et apparaissent dans le Finder sous la forme d’un fichier unique plutôt que d’un répertoire. Liens symboliques—Mac OS, Linux, et Windows Vista prennent en charge les liens symboliques. Les liens symboliques permettent à un fichier de pointer vers un autre fichier ou répertoire du disque. Bien que similaires aux alias, les liens symboliques diffèrent toutefois de ceux-ci. Un alias est systématiquement identifié en tant que fichier (plutôt que répertoire). La lecture d’un alias (ou raccourci) ou l’écriture dans celui-ci n’a aucune incidence sur le fichier ou le répertoire d’origine vers lequel il pointe. En revanche, un lien symbolique se comporte exactement comme le fichier ou le répertoire vers lequel il pointe. Il peut être identifié en tant que fichier ou répertoire. La lecture d’un lien symbolique ou l’écriture dans celui-ci affecte le fichier ou le répertoire vers lequel il pointe, pas le lien symbolique luimême. De plus, sous Windows, la propriété isSymbolicLink d’un objet File référençant un point de jonction (utilisé dans le système de fichiers NTFS) est définie sur true. La classe File comprend les propriétés isPackage et isSymbolicLink qui permettent de vérifier si un objet File référence un package ou un lien symbolique. Le code suivant effectue une itération sur le répertoire du poste de travail de l’utilisateur, répertoriant les sousrépertoires qui ne sont pas des packages : var desktopNodes:Array = File.desktopDirectory.getDirectoryListing(); for (var i:uint = 0; i < desktopNodes.length; i++) { if (desktopNodes[i].isDirectory && !desktopNodes[i].isPackage) { trace(desktopNodes[i].name); } Si l’objet File référence un répertoire, la propriété spaceAvailable indique l’espace que peuvent utiliser les fichiers dans le répertoire. Si l’objet File référence un fichier, la propriété spaceAvailable indique l’espace maximal que peut occuper le fichier. Si l’emplacement de fichier n’existe pas, la propriété spaceAvailable est définie sur 0. Si l’objet File référence un lien symbolique, la propriété spaceAvailable est définie sur l’espace disponible à l’emplacement vers lequel pointe le lien symbolique. En règle générale, l’espace disponible pour un répertoire ou un fichier correspond à l’espace disponible sur le volume contenant ce répertoire ou fichier. Cependant, l’espace disponible peut tenir compte de quotas et de limites par répertoire. Lors de l’ajout d’un fichier ou d’un répertoire à un volume, l’espace nécessaire est généralement supérieur à la taille réelle du fichier ou à la taille du contenu du répertoire. Il se peut, par exemple, que le système d’exploitation requiert de l’espace supplémentaire pour stocker des informations d’index. Les secteurs de disque requis utilisent peut-être de l’espace en plus. En outre, l’espace disponible change dynamiquement. Il est donc impossible d’allouer tout l’espace indiqué au stockage des fichiers. Pour plus d’informations sur l’écriture dans le système de fichiers, voir la section « Lecture et écriture de fichiers » à la page 715. La méthode StorageVolumeInfo.getStorageVolumes() propose des informations plus détaillées sur les volumes de stockage montés (voir « Utilisation des volumes de stockage » à la page 713).
Adobe AIR 2 et ultérieur AIR 2 permet d’ouvrir un fichier dans l’application enregistrée à cet effet par le système d’exploitation. Une application AIR peut ainsi ouvrir un fichier DOC dans l’application enregistrée à cet effet. Faites appel à la méthode openWithDefaultApplication() d’un objet File pour ouvrir le fichier. Le code suivant ouvre par exemple le fichier test.doc sur le bureau de l’utilisateur dans l’application associée par défaut aux fichiers DOC : var file:File = File.deskopDirectory; file = file.resolvePath("test.doc"); file.openWithDefaultApplication();
Windows, AIR vous interdit d’ouvrir les fichiers de type EXE ou BAT, par exemple. Sous Mac OS et Linux, AIR vous empêche d’ouvrir les fichiers qui s’exécutent dans une application spécifique (y compris Terminal et AppletLauncher sous Mac OS, ainsi que csh, bash ou ruby sous Linux). Tenter d’ouvrir l’un de ces fichiers par le biais de la méthode openWithDefaultApplication() renvoie une exception. Pour obtenir la liste complète des types de fichiers concernés, voir la rubrique du guide de référence du langage consacrée à la méthode File.openWithDefaultApplication(). Remarque : cette limitation n’existe pas pour une application AIR installée à l’aide d’un programme d’installation natif (application de bureau étendue).
Adobe AIR 1.0 et les versions ultérieures La classe File comprend les propriétés statiques suivantes, qui fournissent des renseignements utiles sur le système de fichiers : Propriété
Le moteur d’exécution vous permet de manipuler les répertoires du système de fichiers local. Pour plus de détails sur la création d’objets File qui pointent vers des répertoires, voir la section « Pointage d’un objet File vers un répertoire » à la page 696.
Adobe AIR 1.0 et les versions ultérieures La méthode File.createDirectory() permet de créer un répertoire. Par exemple, le code suivant crée le répertoire AIR Test en tant que sous-répertoire du répertoire d’accueil de l’utilisateur : var dir:File = File.userDirectory.resolvePath("AIR Test"); dir.createDirectory();
Par ailleurs, dans certains modes, un objet FileStream crée des répertoires à l’ouverture des fichiers. Les répertoires qui n’existent pas sont créés lorsque vous instanciez une occurrence de FileStream en définissant le paramètre fileMode du constructeur FileStream() sur FileMode.APPEND ou FileMode.WRITE. Pour plus d’informations, voir la section « Flux de travail pour la lecture et l’écriture de fichiers » à la page 715.
Adobe AIR 1.0 et les versions ultérieures La classe File comprend la méthode createTempDirectory(), qui crée un répertoire dans le répertoire temporaire système, comme l’illustre l’exemple suivant : var temp:File = File.createTempDirectory();
Vous pouvez éventuellement supprimer le répertoire temporaire avant de fermer l’application, car cette opération n’est pas automatiquement effectuée sur tous les périphériques.
Adobe AIR 1.0 et les versions ultérieures Les méthodes getDirectoryListing() ou getDirectoryListingAsync() d’un objet File permettent d’obtenir un tableau d’objets File pointant vers les fichiers et sous-répertoires d’un répertoire. Par exemple, le code suivant répertorie le contenu du répertoire de documents de l’utilisateur (sans examiner les sousrépertoires) : var directory:File = File.documentsDirectory; var contents:Array = directory.getDirectoryListing(); for (var i:uint = 0; i < contents.length; i++) { trace(contents[i].name, contents[i].size); } Lorsque vous définissez le paramètre overwrite de la méthode copyTo() sur true, tous les fichiers et dossiers d’un répertoire cible existant sont supprimés et remplacés par les fichiers et dossiers du répertoire source (même si le fichier cible n’existe pas dans le répertoire source). Le répertoire sur lequel vous définissez le paramètre newLocation de la méthode copyTo() spécifie le chemin d’accès au répertoire résultant, et non le répertoire parent qui contiendra le répertoire résultant.
Suppression du contenu d’un répertoire Adobe AIR 1.0 et les versions ultérieures La classe File comprend les méthodes deleteDirectory() et deleteDirectoryAsync(). Ces méthodes suppriment des répertoires. La première s’exécute en mode synchrone et la seconde en mode asynchrone (voir la section « Principes de base des classes File d’AIR » à la page 692). Elles comprennent toutes deux le paramètre deleteDirectoryContents (qui accepte une valeur booléenne). Lorsque ce paramètre est défini sur true (la valeur par défaut correspond à false), l’appel de la méthode supprime les répertoires non vides ; sinon, seuls les répertoires vides sont supprimés. Par exemple, le code suivant supprime en mode synchrone le sous-répertoire AIR Test du répertoire de documents de l’utilisateur : var directory:File = File.documentsDirectory.resolvePath("AIR Test"); directory.deleteDirectory(true);
} L’API de fichiers d’AIR vous permet d’ajouter des fonctionnalités de manipulation des fichiers de base à vos applications. Vous pouvez ainsi accéder à des fichiers en lecture ou en écriture, copier et supprimer des fichiers, etc. Comme vos applications ont accès au système de fichiers local, voir le chapitre « Sécurité AIR » à la page 1122, si ce n’est déjà fait. Remarque : vous pouvez associer un type de fichier à une application AIR (afin qu’un double-clic sur le fichier entraîne l’ouverture de l’application). Pour plus d’informations, voir la section « Gestion des associations de fichiers » à la page 920.
Adobe AIR 1.0 et les versions ultérieures La classe File comprend les propriétés suivantes qui fournissent des informations sur un fichier ou un répertoire vers lequel pointe un objet File :
ActionScript 3.0 pour la plate-forme Adobe Flash.
Adobe AIR 1.0 et les versions ultérieures La classe File comprend deux méthodes permettant de copier des fichiers ou des répertoires : copyTo() et copyToAsync(). Elle propose également deux méthodes permettant de déplacer des fichiers ou des répertoires : moveTo() et moveToAsync(). Les méthodes copyTo() et moveTo() s’exécutent en mode synchrone, les méthodes copyToAsync() et moveToAsync() en mode asynchrone (voir la section « Principes de base des classes File d’AIR » à la page 692). Pour copier ou déplacer un fichier, vous définissez deux objets File. L’un pointe vers le fichier à copier ou déplacer et appelle la méthode copy ou move. L’autre pointe vers le chemin de destination (résultant). Le code suivant copie le fichier test.txt qui réside dans le sous-répertoire AIR Test du répertoire de documents de l’utilisateur vers le fichier copy.txt dans le même répertoire :
Par exemple, le code suivant supprime, en mode synchrone, le fichier test.txt du répertoire de documents de l’utilisateur : var file:File = File.documentsDirectory.resolvePath("test.txt"); file.deleteFile();
(voir la section « Principes de base des classes File d’AIR » à la page 692). Par exemple, le code suivant déplace, en mode synchrone, le fichier test.txt du répertoire de documents de l’utilisateur vers la corbeille système : var file:File = File.documentsDirectory.resolvePath("test.txt"); file.moveToTrash();
Adobe AIR 1.0 et les versions ultérieures La classe File comprend la méthode createTempFile(), qui crée un fichier dans le répertoire temporaire système, comme l’illustre l’exemple suivant : var temp:File = File.createTempFile();
Vous pouvez utiliser un fichier temporaire pour stocker provisoirement des informations utilisées au cours d’une session de l’application. Vous remarquerez que vous disposez également de la méthode createTempDirectory(), qui permet de créer un répertoire temporaire unique dans le répertoire temporaire système. Vous pouvez éventuellement supprimer le fichier temporaire avant de fermer l’application, car cette opération n’est pas automatiquement effectuée sur tous les périphériques.
Adobe AIR 2 et ultérieur AIR 2 permet de détecter le montage ou le démontage des volumes de stockage de masse. La classe StorageVolumeInfo définit un objet storageVolumeInfo singleton. L’objet StorageVolumeInfo.storageVolumeInfo distribue un événement storageVolumeMount lors du montage d’un volume de stockage. Il distribue également un événement storageVolumeUnmount lors du démontage d’un volume. La classe StorageVolumeChangeEvent définit ces événements. Remarque : sur les distributions récentes de Linux, l’objet StorageVolumeInfo ne distribue les événements storageVolumeMount et storageVolumeUnmount que pour les périphériques physiques et les lecteurs réseau montés à des emplacements déterminés.
La propriété storageVolume de la classe StorageVolumeChangeEvent est un objet StorageVolume. La classe StorageVolume définit les propriétés de base du volume de stockage :
• à null) si le volume est démonté. Vous pouvez toutefois accéder à la propriété rootDirectory de l’événement. Le code suivant indique le nom et le chemin d’un volume de stockage lorsqu’il est monté : StorageVolumeInfo.storageVolumeInfo.addEventListener(StorageVolumeChangeEvent.STORAGE_VOLUME _MOUNT, onVolumeMount); function onVolumeMount(event:StorageVolumeChangeEvent):void { trace(event.storageVolume.name, event.rootDirectory.nativePath); La méthode File.getRootDirectories() recense les répertoires racine (voir « Pointage vers la racine du système de fichiers » à la page 698). Les objets StorageVolume (énumérés par la méthode StorageVolumeInfo.getStorageVolumes()) proposent toutefois plus d’informations sur les volumes de stockage. Vous disposez de la propriété spaceAvailable de la propriété rootDirectory d’un objet StorageVolume pour obtenir l’espace disponible sur un volume de stockage. (Voir « Détermination de l’espace disponible sur un volume » à la page 706.)
La classe FileStream permet aux applications AIR de lire et d’écrire dans le système de fichiers.
Adobe AIR 1.0 et les versions ultérieures Le flux de travail de lecture et d’écriture de fichier est décrit ci-après. Initialisez un objet File pointant vers le chemin. Cet objet File représente le chemin du fichier que vous souhaitez utiliser (ou d’un fichier que vous créerez ultérieurement). var file:File = File.documentsDirectory; file = file.resolvePath("AIR Test/testFile.txt");
Initialisez un objet FileStream. Appelez la méthode open() ou openAsync() de l’objet FileStream. La méthode que vous appelez varie selon que vous souhaitez ouvrir le fichier en mode synchrone ou asynchrone. Utilisez l’objet File comme paramètre file de la méthode open. Pour le paramètre fileMode, spécifiez une constante de la classe FileMode qui définit le mode d’utilisation du fichier. Par exemple, le code suivant initialise un objet FileStream utilisé pour créer un fichier et, éventuellement, remplacer les données existantes : var fileStream:FileStream = new FileStream(); fileStream.open(file, FileMode.WRITE);
à la page 717 et « Modes d’ouverture FileStream » à la page 716. Si vous avez ouvert le fichier en mode asynchrone (à l’aide de la méthode openAsync()), ajoutez et définissez des écouteurs d’événement pour l’objet FileStream. Ces méthodes d’écouteurs d’événements réagissent aux événements distribués par l’objet FileStream dans divers cas de figure. Parmi ces cas de figure figurent notamment la lecture de données dans le fichier, la génération d’erreurs E/S ou l’écriture de l’intégralité des données. Pour plus d’informations, voir la section « Programmation asynchrone et événements générés par un objet FileStream ouvert en mode asynchrone » à la page 721.
La classe FileStream propose de nombreuses méthodes relatives à la lecture ou l’écriture (elles commencent toutes par « read » ou « write »). La méthode que vous choisissez pour lire et écrire des données varie en fonction du format des données dans le fichier cible. Par exemple, si les données du fichier cible sont au format texte UTF, vous pouvez utiliser les méthodes readUTFBytes() et writeUTFBytes(). Pour manipuler les données en tant que tableaux d’octets, utilisez les méthodes readByte(), readBytes(), writeByte() et writeBytes(). Pour plus d’informations, voir la section « Format de données et choix des méthodes de lecture et d’écriture » à la page 722. Si vous avez ouvert le fichier en mode asynchrone, veillez à ce qu’un volume suffisant de données soit disponible avant d’appeler une méthode de lecture. Pour plus d’informations, voir la section « Mémoire tampon de lecture et propriété bytesAvailable d’un objet FileStream » à la page 719. Si, avant d’accéder en écriture à un fichier, vous souhaitez vérifier la quantité d’espace disque disponible, vous pouvez consulter la propriété spaceAvailable de l’objet File. Pour plus d’informations, voir la section « Détermination de l’espace disponible sur un volume » à la page 706. Appelez la méthode close() de l’objet FileStream lorsque vous avez terminé de manipuler le fichier. D’autres applications peuvent alors accéder à ce dernier. Pour plus d’informations, voir la section « Initialisation d’un objet FileStream et ouverture et fermeture de fichiers » à la page 717. Vous trouverez un exemple d’application utilisant la classe FileStream pour accéder en lecture et en écriture à des fichiers dans les articles suivants du Centre des développeurs Adobe AIR :
• Développement d’un éditeur de fichier texte
Adobe AIR 1.0 et les versions ultérieures La classe FileStream définit des méthodes permettant d’ouvrir des fichiers et d’y accéder en lecture ou en écriture. Modes d’ouverture FileStream Adobe AIR 1.0 et les versions ultérieures Les méthodes open() et openAsync() d’un objet FileStream comprennent le paramètre fileMode, qui définit certaines propriétés d’un flux de fichier, pour indiquer notamment :
• s’il est possible d’accéder au fichier en écriture ; • si les données sont systématiquement ajoutées à la fin du fichier (lors de l’écriture) ; • que faire lorsque le fichier n’existe pas (et que ses répertoires parent n’existent pas). Les différents modes de fichier disponibles (que vous pouvez spécifier dans le paramètre fileMode des méthodes open() et openAsync()) sont les suivants :
Choisissez ce mode pour un accès en lecture/écriture aléatoire au fichier. Vous pouvez lire à partir de tout emplacement du fichier. Lorsque vous écrivez dans celui-ci, seuls les octets écrits remplacent les octets existants (aucun autre octet n’étant affecté).
Adobe AIR 1.0 et les versions ultérieures Lorsque vous ouvrez un objet FileStream, vous autorisez un accès en lecture ou en écriture à un fichier. Pour ouvrir un objet FileStream, vous transmettez un objet File à sa méthode open() ou openAsync() : var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt"); var myFileStream:FileStream = new FileStream(); myFileStream.open(myFile, FileMode.READ);
« Modes d’ouverture FileStream » à la page 716. Si vous ouvrez le fichier en mode asynchrone à l’aide de la méthode openAsync(), configurez des écouteurs d’événement pour gérer les événements asynchrones : var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt"); var myFileStream:FileStream = new FileStream(); myFileStream.addEventListener(Event.COMPLETE, completeHandler); myFileStream.addEventListener(ProgressEvent.PROGRESS, progressHandler); myFileStream.addEventListener(IOErrorEvent.IO_Error, errorHandler); myFileStream.open(myFile, FileMode.READ); function completeHandler(event:Event):void { // ... } function progressHandler(event:ProgressEvent):void { Dernière mise à jour le 27/4/2013
FileStream. Pour plus d’informations, voir la section « Mémoire tampon de lecture et propriété bytesAvailable d’un objet FileStream » à la page 719. Vous pouvez appeler la méthode close() d’un objet FileStream pour fermer le fichier associé, ce qui le met à la disposition d’autres applications. Propriété position d’un objet FileStream Adobe AIR 1.0 et les versions ultérieures La propriété position d’un objet FileStream détermine l’emplacement de lecture ou d’écriture des données de la méthode de lecture ou d’écriture suivante. Préalablement à une opération de lecture ou d’écriture, définissez la propriété position sur une position valide dans le fichier. Par exemple, le code suivant écrit la chaîne "hello" (au codage UTF) à la position 8 dans le fichier : var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt"); var myFileStream:FileStream = new FileStream(); myFileStream.open(myFile, FileMode.UPDATE); myFileStream.position = 8; myFileStream.writeUTFBytes("hello");
Avant une opération de lecture, la valeur de la propriété position doit être comprise entre 0 et le nombre maximal d’octets du fichier (autrement dit, une position existante dans le fichier). La valeur de la propriété position est uniquement modifiée dans les cas suivants :
• Vous appelez une méthode de lecture. • Vous appelez une méthode d’écriture. Lorsque vous appelez une méthode de lecture ou d’écriture d’un objet FileStream, la propriété position est immédiatement incrémentée du nombre d’octets lus ou écrits. Selon la méthode de lecture utilisée, la propriété position est incrémentée du nombre d’octets que vous spécifiez pour la lecture ou du nombre d’octets disponibles. Lorsque, par la suite, vous appelez une méthode de lecture ou d’écriture, elle commence la lecture ou l’écriture à la nouvelle position. var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt"); var myFileStream:FileStream = new FileStream(); myFileStream.open(myFile, FileMode.UPDATE); myFileStream.position = 4000; trace(myFileStream.position); // 4000 myFileStream.writeBytes(myByteArray, 0, 200); trace(myFileStream.position); // 4200
Lors de l’ouverture d’un objet FileStream doté de fonctionnalités de lecture (le paramètre fileMode de sa méthode open() ou openAsync() étant défini sur READ ou UPDATE), le moteur d’exécution stocke les données dans une mémoire tampon interne. L’objet FileStream commence la lecture et l’insertion des données dans la mémoire tampon dès l’ouverture du fichier (par appel de la méthode open() ou openAsync() de l’objet FileStream). Si un fichier est ouvert en mode synchrone (à l’aide de la méthode open()), vous pouvez définir le pointeur position sur n’importe quelle position valide (dans les limites du fichier) et commencer à lire tout volume de données (dans les limites du fichier), comme l’illustre le code suivant (qui considère comme acquis que le fichier contient au moins 100 octets) :
En mode asynchrone, vous devez vous assurer que la mémoire tampon de lecture contient suffisamment de données avant d’appeler une méthode de lecture. Dans ce mode, au fur et à mesure de la lecture, les données du fichier sont ajoutées à la mémoire tampon, à partir de la position spécifiée au début de l’opération de lecture, et la propriété bytesAvailable est incrémentée à chaque octet lu. La propriété bytesAvailable indique le nombre d’octets disponibles entre l’octet situé à la position spécifiée par la propriété position et la fin de la mémoire tampon. L’objet FileStream envoie régulièrement un événement progress. En mode asynchrone, l’objet FileStream distribue régulièrement l’événement progress à mesure que des données sont disponibles dans la mémoire tampon de lecture. Par exemple, le code suivant insère des données dans un objet ByteArray, bytes, au fur et à mesure de leur insertion dans la mémoire tampon de lecture : var bytes:ByteArray = new ByteArray(); var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt"); var myFileStream:FileStream = new FileStream(); myFileStream.addEventListener(ProgressEvent.PROGRESS, progressHandler); myFileStream.openAsync(myFile, FileMode.READ); function progressHandler(event:ProgressEvent):void { myFileStream.readBytes(bytes, myFileStream.position, myFileStream.bytesAvailable); }
Programmation asynchrone et événements générés par un objet FileStream ouvert en mode asynchrone Adobe AIR 1.0 et les versions ultérieures Lorsqu’un fichier est ouvert en mode asynchrone (à l’aide de la méthode openAsync()), la lecture et l’écriture de fichiers sont asynchrones. Un autre code ActionScript peut s’exécuter au fur et à mesure de l’insertion de données dans la mémoire tampon de lecture et de l’écriture de données de sortie. Vous devez donc vous enregistrer pour les événements générés par l’objet FileStream ouvert en mode asynchrone. En vous enregistrant pour l’événement progress, vous pouvez être averti dès que de nouvelles données sont disponibles à des fins de lecture, comme l’illustre le code suivant : var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt"); var myFileStream:FileStream = new FileStream(); myFileStream.addEventListener(ProgressEvent.PROGRESS, progressHandler); myFileStream.openAsync(myFile, FileMode.READ); var str:String = ""; function progressHandler(event:ProgressEvent):void { str += myFileStream.readMultiByte(myFileStream.bytesAvailable, "iso-8859-1"); }
OutputProgressEvent. Un objet OutputProgressEvent comprend une propriété bytesPending définie sur le nombre d’octets restants à écrire. Vous pouvez vous enregistrer pour l’événement outputProgress afin d’être averti lorsque cette mémoire tampon est écrite dans le fichier, peut-être pour afficher une boîte de dialogue de progression. Toutefois, cette opération n’est généralement pas nécessaire. Vous pouvez notamment appeler la méthode close() sans vous soucier des octets non écrits. L’objet FileStream continue d’écrire des données et l’événement close est envoyé une fois le dernier octet écrit dans le fichier et le fichier sous-jacent fermé. Format de données et choix des méthodes de lecture et d’écriture Adobe AIR 1.0 et les versions ultérieures Tout fichier est un ensemble d’octets sur disque. Dans ActionScript, les données d’un fichier peuvent toujours être représentées sous la forme d’un objet ByteArray. Par exemple, le code suivant lit les données d’un fichier et les insère dans un objet ByteArray nommé bytes : var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt"); var myFileStream:FileStream = new FileStream(); myFileStream.addEventListener(Event.COMPLETE, completeHandler); myFileStream.openAsync(myFile, FileMode.READ); var bytes:ByteArray = new ByteArray(); function completeHandler(event:Event):void { myFileStream.readBytes(bytes, 0, myFileStream.bytesAvailable); }
C’est pourquoi la classe FileStream comprend des méthodes de lecture et d’écriture de données de types autres que les objets ByteArray. Par exemple, la méthode readMultiByte() permet de lire des données dans un fichier et de les stocker dans une chaîne, comme l’illustre le code suivant :
(Cette règle s’applique également à l’utilisation de la méthode readMultiByte() avec un codage de caractères de longueur variable.) Lorsque l’objet FileStream distribue l’événement progress, vous devez donc lire l’ensemble complet de données. Vous disposez également de méthodes d’écriture similaires, writeMultiByte() et writeUTFBytes(), pour manipuler les objets String et les fichiers de texte. Les méthodes readUTF() et writeUTF() (à ne pas confondre avec readUTFBytes() et writeUTFBytes()) permettent également la lecture ou l’écriture de données dans un fichier, mais elles considèrent comme acquis que des données indiquant la longueur des données texte précèdent ces dernières, ce qui n’est pas une pratique courante dans les fichiers de texte standard. Certains fichiers de texte UTF commencent par un caractère « UTF-BOM » (de l’anglais Byte Order Mark) qui définit le boutisme, ainsi que le format de codage (UTF-16 ou UTF-32). Vous trouverez un exemple de lecture et d’écriture dans un fichier de texte à la section « Exemple : Lecture et insertion d’un fichier XML dans un objet XML » à la page 725. Les méthodes readObject() et writeObject() facilitent le stockage et la récupération de données pour les objets ActionScript complexes. Les données sont codées au format AMF (ActionScript Message Format). Adobe AIR, Flash Player, Flash Media Server et Flex Data Services comprennent des API permettant de manipuler les données dans ce format. Il existe d’autres méthodes de lecture et d’écriture, notamment readDouble() et writeDouble(). Cependant si vous les utilisez, assurez-vous que le format de fichier correspond au format des données définies par ces méthodes. Les formats de fichier sont souvent plus complexes que de simples formats de texte. Par exemple, un fichier MP3 contient des données compressées qui peuvent uniquement être interprétées par le biais des algorithmes de décompression et de décodage spécifiques à ce format. Les fichiers MP3 peuvent également comprendre des balises ID3 qui contiennent des informations de métabalise concernant le fichier (tel que le titre et l’interprète d’une chanson). Il existe plusieurs versions du format ID3, mais le plus simple (ID3 version 1) est présenté à la section « Exemple : Lecture et écriture de données en mode aléatoire » à la page 726. D’autres formats de fichier (pour les images, bases de données, documents d’application, etc.) ont une structure de données différente. Vous devez comprendre celle-ci pour pouvoir les utiliser dans ActionScript.
Flash Player 10 et les versions ultérieures, Adobe AIR 1.5 et les versions ultérieures Flash Player 10 a ajouté les méthodes load() et save() dans la classe FileReference. Ces méthodes sont également présentes dans AIR 1.5, et la classe File hérite des méthodes de la classe FileReference. L’objectif de ces méthodes est de fournir aux utilisateurs un moyen sécurisé pour charger et enregistrer les données des fichiers dans Flash Player. Toutefois, les applications AIR peuvent également les utiliser pour charger et enregistrer les fichiers de façon asynchrone. Par exemple, le code suivant enregistre une chaîne dans un fichier texte : var file:File = File.applicationStorageDirectory.resolvePath("test.txt"); var str:String = "Hello."; file.addEventListener(Event.COMPLETE, fileSaved); file.save(str); function fileSaved(event:Event):void { trace("Done."); }
• La classe FileStream vous permet d’ouvrir un fichier en mode aléatoire (lecture et écriture dans toute section du fichier).
Les exemples suivants expliquent comment accéder en lecture et en écriture à un fichier de texte contenant des données XML. Pour lire le fichier, initialisez les objets File et FileStream, appelez la méthode readUTFBytes() de l’objet FileStream et convertissez la chaîne en objet XML : var file:File = File.documentsDirectory.resolvePath("AIR Test/preferences.xml"); var fileStream:FileStream = new FileStream(); fileStream.open(file, FileMode.READ); var prefsXML:XML = XML(fileStream.readUTFBytes(fileStream.bytesAvailable)); fileStream.close();
« Format de données et choix des méthodes de lecture et d’écriture » à la page 722). Les exemples précédents utilisent des objets FileStream ouverts en mode synchrone. Vous pouvez aussi ouvrir des fichiers en mode asynchrone (ce type d’opération nécessite l’utilisation de fonctions d’écouteur d’événement pour répondre aux événements). Par exemple, le code suivant illustre comment lire un fichier XML en mode asynchrone : var file:File = File.documentsDirectory.resolvePath("AIR Test/preferences.xml"); var fileStream:FileStream = new FileStream(); fileStream.addEventListener(Event.COMPLETE, processXMLData); fileStream.openAsync(file, FileMode.READ); var prefsXML:XML; function processXMLData(event:Event):void { prefsXML = XML(fileStream.readUTFBytes(fileStream.bytesAvailable)); fileStream.close(); }
Exemple : Lecture et écriture de données en mode aléatoire Adobe AIR 1.0 et les versions ultérieures Les fichiers MP3 peuvent renfermer des balises ID3, autrement dit, des sections en début ou fin de fichier contenant des métadonnées identifiant l’enregistrement. Il existe différentes versions du format de balise ID3. L’exemple suivant explique comment accéder en lecture et écriture à un fichier MP3 contenant le format ID3 le plus simple (ID3 version 1.0) par le biais d’un « accès aléatoire aux données », c’est-à-dire en lisant et écrivant des données à des emplacements arbitraires dans le fichier. Dans un fichier MP3 contenant une balise ID3 version 1, les données ID3 figurent dans les 128 derniers octets du fichier. Lorsque vous accédez à un fichier en mode de lecture/écriture aléatoire, il est important de définir le paramètre fileMode de la méthode open() ouopenAsync() sur FileMode.UPDATE : var file:File = File.documentsDirectory.resolvePath("My Music/Sample ID3 v1.mp3"); var fileStr:FileStream = new FileStream(); fileStr.open(file, FileMode.UPDATE);
A l’ouverture du fichier, vous pouvez définir le pointeur position sur 128 octets avant la fin du fichier : fileStr.position = file.size - 128;
• Les 30 caractères suivants représentent le titre de la piste MP3, sous forme de chaîne. • Les 30 caractères suivants représentent le nom de l’interprète, sous forme de chaîne. • Les 30 caractères suivants représentent le nom de l’album, sous forme de chaîne. • Les 4 caractères suivants représentent l’année, sous forme de chaîne. • Les 30 caractères suivants représentent le commentaire, sous forme de chaîne. • L’octet suivant contient un code identifiant le genre de la piste. • Toutes les données texte sont au format ISO 8859-1. La méthode id3TagRead() vérifie les données après leur lecture (sur envoi de l’événement complete) :
Il est également possible de lire et d’écrire des fichiers dans le système de fichiers et, dans Adobe AIR, d’accéder aux fichiers de base de données locaux. Pour plus d’informations, voir « Utilisation du système de fichiers » à la page 676 et « Utilisation des bases de données SQL locales dans AIR » à la page 741. Diverses considérations liées à la sécurité affectent les objets partagés. Pour plus d’informations, voir « Objets partagés » à la page 1120 dans « Sécurité » à la page 1085.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Un objet partagé, parfois appelé cookie Flash, est un fichier de données qui peut être créé sur votre ordinateur par les sites que vous visitez. Les objets partagés servent le plus souvent à optimiser la navigation sur le Web, par exemple en vous permettant de personnaliser l’aspect d’un site Web que vous consultez fréquemment.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les objets partagés fonctionnent comme des cookies de navigation. La classe SharedObject permet de stocker des données sur le disque dur local de l’utilisateur et d’appeler ces données pendant la même session ou dans le cadre d’une session ultérieure. Les applications peuvent accéder uniquement à leurs propres données SharedObject, et ce, uniquement si elles sont exécutées sur le même domaine. Les données ne sont pas transmises au serveur et les applications exécutées dans d’autres domaines ne peuvent pas y accéder. En revanche, les applications du même domaine sont en mesure d’y accéder.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les cookies et les objets partagés sont très similaires. Comme la plupart des programmateurs Web connaissent le fonctionnement des cookies, la comparaison des cookies et des objets SharedObjects locaux peut s’avérer utile. Les cookies conformes au standard RFC 2109 possèdent habituellement les propriétés suivantes :
• Ils sont désactivables par le client en fonction de sites spécifiques. • La limite totale de cookies est de 300, avec 20 cookies maximum par site. • Leur taille est habituellement limitée à 4 Ko chacun.
Stockage des données locales
• Ils sont stockés dans un emplacement spécifié par le navigateur client. • Ils sont transmis du client au serveur via HTTP. Par contre, les objets partagés possèdent les propriétés suivantes :
• Par défaut, leur taille est limitée à 100 Ko chacun. • Ils peuvent enregistrer des types de données simples (comme String, Array et Date). • Ils sont stockés à un emplacement spécifié par l’application (dans le répertoire de base de l’utilisateur). • Ils ne sont jamais transmis entre le client et le serveur.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe SharedObject permet de créer et de supprimer des objets partagés, ainsi que de détecter la taille actuelle d’un objet SharedObject en cours d’utilisation.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour créer un objet SharedObject, faites appel à la méthode SharedObject.getLocal(), dont la syntaxe est la suivante : SharedObject.getLocal("objectName" [, pathname]): SharedObject
SharedObject localement dans le répertoire de base du client. A la création d’un objet partagé, Flash Player crée un nouveau répertoire pour l’application et le domaine dans son sandbox. Il crée également un fichier *.sol qui enregistre les données SharedObject. L’emplacement par défaut de ce fichier est un sous-répertoire du répertoire de base de l’utilisateur. Le tableau suivant indique les emplacements par défaut de ce répertoire : Système d’exploitation
Par exemple, si vous demandez un application nommée MyApp.swf sur l’hôte local et dans un sous-répertoire nommé /sos, Flash Player enregistre le fichier *.sol à l’emplacement suivant sur Windows XP: c:/Documents and Settings/fred/Application Data/Macromedia/Flash Player/#SharedObjects/KROKWXRK/#localhost/sos/MyApp.swf/data.sol
Par défaut, Flash peut enregistrer des objets SharedObject persistants localement, d’une taille maximale de 100 Ko par domaine. Cette valeur est configurable par l’utilisateur. Lorsque l’application tente d’enregistrer un objet partagé d’une taille supérieure à 100 Ko, Flash Player affiche la boîte de dialogue Stockage local, qui permet à l’utilisateur d’autoriser ou de refuser une augmentation du volume de stockage local pour le domaine qui demande l’accès.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le paramètre facultatif pathname permet de spécifier l’emplacement du fichier SharedObject. Ce fichier doit être un sous-répertoire du répertoire SharedObject de ce domaine. Par exemple, si vous demandez une application sur l’hôte local et spécifiez ce qui suit : mySO = SharedObject.getLocal("myObjectFile","/");
Cela s’avère utile si vous souhaitez plusieurs applications sur le client pour pouvoir accéder au même objet partagé. Dans ce cas, le client peut exécuter deux applications Flex, qui spécifient un chemin vers l’objet partagé qui est la racine du domaine ; le client peut ensuite accéder au même objet partagé à partir des deux applications. Pour partager des données entre plusieurs applications sans persistance, vous pouvez utiliser l’objet LocalConnection. Si vous spécifiez un répertoire inexistant, Flash Player ne crée pas de fichier SharedObject.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous ajoutez des données à un fichier *.sol d’objet SharedObject à l’aide de sa propriété data. Pour ajouter de nouvelles données à l’objet partagé, utilisez la syntaxe suivante : sharedObject_name.data.variable = value;
SharedObject : public var currentUserName:String = "Reiner"; public var itemsArray:Array = new Array(101,346,483); public var currentUserIsAdmin:Boolean = true; mySO.data.userName = currentUserName; mySO.data.itemNumbers = itemsArray; mySO.data.adminPrivileges = currentUserIsAdmin;
SharedObject. Pour forcer Flash Player à écrire les valeurs dans le fichier SharedObject, utilisez la méthode SharedObject.flush(), comme suit :
Player (www.macromedia.com/support/documentation/fr/flashplayer/help/settings_manager07.html), comme illustré dans cet exemple : var so:SharedObject = SharedObject.getLocal("test"); trace("Current SharedObject size is " + so.size + " bytes."); so.flush();
Vous pouvez stocker des objets simples comme Arrays ou Strings dans la propriété data de l’objet SharedObject. L’exemple suivant est une class ActionScript qui définit des méthodes contrôlant l’interaction avec l’objet partagé. Ces méthodes permettent à l’utilisateur d’ajouter et de supprimer des objets de l’objet partagé. Cette classe stocke une collection ArrayCollection qui contient des objets simples. package { import mx.collections.ArrayCollection; import flash.net.SharedObject; public class LSOHandler { private var mySO:SharedObject; private var ac:ArrayCollection; private var lsoType:String; // The parameter is "feeds" or "sites". public function LSOHandler(s:String) { init(s); } private function init(s:String):void { ac = new ArrayCollection(); lsoType = s; mySO = SharedObject.getLocal(lsoType); if (getObjects()) {
Dernière mise à jour le 27/4/2013
Vous pouvez définir la propriété SharedObject.preventBackup de manière à contrôler si les objets locaux partagés sont sauvegardés sur le service iOS de sauvegarde sur le cloud. Apple demande de procéder de cette manière pour tout contenu qu’il est possible de générer ou télécharger à nouveau, mais qui est nécessaire au bon fonctionnement de votre application lors d’une utilisation hors ligne.
Vous pouvez créer plusieurs objets partagés pour la même application Flex. Pour ce faire, affectez à chacun d’entre eux un nom d’occurrence différent, comme indiqué dans l’exemple suivant : public var mySO:SharedObject = SharedObject.getLocal("preferences"); public var mySO2:SharedObject = SharedObject.getLocal("history");
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lorsque vous créez un SharedObject local ou distant à l’aide de getLocal() ou getRemote(), un paramètre facultatif nommé secure détermine si l’accès à l’objet partagé se limite aux fichiers SWF diffusés via une connexion HTTPS. Si ce paramètre a la valeur true et que votre fichier SWF est diffusé sur HTTPS, Flash Player crée un nouvel objet sécurisé ou obtient une référence à un objet partagé sécurisé existant. Cet objet partagé sécurisé peut uniquement être lu ou écrit par des fichiers SWF reçus via des connexions HTTPS appelant SharedObject.getLocal() avec le paramètre secure réglé sur true. Si ce paramètre a la valeur false et que votre fichier SWF est diffusé sur HTTPS, Flash Player crée un nouvel objet partagé ou obtient une référence à un objet partagé existant. Cet objet partagé peut être lu ou écrit par des fichiers SWF reçus via des connexions autres que HTTPS. Si votre fichier SWF est diffusé via une connexion autre que HTTPS et que vous essayez de régler ce paramètre sur true, la création d’un objet partagé (ou l’accès à un objet partagé sécurisé précédemment créé) échoue, une erreur est renvoyée et l’objet partagé devient null. Si vous tentez d’exécuter l’extrait de code suivant à partir d’un connexion non HTTPS, la méthode SharedObject.getLocal() renvoie une erreur : try { var so:SharedObject = SharedObject.getLocal("contactManager", null, true); } catch (error:Error) { trace("Unable to create SharedObject."); Des valeurs sont stockées dans un objet partagé, au sein de la propriété data. Vous pouvez passer en boucle chaque valeur d’une occurrence d’objet partagé à l’aide de la boucle for..in, comme le montre l’exemple suivant :
L’exemple suivant commence par un souhait de bienvenue en tant que nouveau visiteur. Lorsque vous cliquez sur Déconnexion, l’application stocke la date actuelle dans un objet partagé. La prochaine fois que vous lancez cette application ou que vous actualisez la page, l’application vous souhaite la bienvenue avec un rappel de l’heure à laquelle vous vous êtes déconnecté. Pour voir l’application en action, lancez-la, cliquez sur Déconnexion, puis réactualisez la page. L’application affiche la date et l’heure auxquelles vous avez cliqué sur le bouton Déconnexion lors de votre précédente visite. Vous pouvez supprimer à tout moment les informations stockées en cliquant sur le bouton Supprimer le LSO.
Dernière mise à jour le 27/4/2013
Sur les plates-formes de bureau, AIR utilise DPAPI sous Windows, KeyChain sous Mac OS et iOS, et KeyRing ou KWallet sous Linux pour associer le magasin local chiffré à chaque application et chaque utilisateur. Le magasin local chiffré utilise le chiffrement AES-CBC 128 bits. Sur Android, les données enregistrées par la classe EncryptedLocalStorage ne sont pas chiffrées. Elles sont protégées par la sécurité de niveau utilisateur fournie par le système d’exploitation. Le système d’exploitation Android affecte à chaque application un ID utilisateur distinct. Les applications peuvent uniquement accéder à leurs propres fichiers et aux fichiers créés dans des emplacements publics (tels que la carte de stockage amovible). Notez que sur les périphériques Android associés à une racine, les applications s’exécutant avec des privilèges racines PEUVENT accéder aux fichiers d’autres applications. Sur ce type de périphérique, le magasin de stockage local ne fournit pas un niveau élevé de protection de données. Les informations stockées dans le magasin local chiffré sont réservées au contenu d’application AIR dans le sandbox de sécurité de l’application. Une version mise à jour d’une application AIR conserve un accès à toute donnée existante stockée dans le magasin local chiffré, sauf si :
• La version existante et la version mise à jour sont toutes deux publiées avant AIR 1.5.3 et la mise à jour est dotée d’une signature de migration. Restrictions du magasin local chiffré Les données stockées dans le magasin local chiffré sont protégées par les informations d’identification du compte sur le système d’exploitation de l’utilisateur. Sauf s’il se connecte sous le nom de cet utilisateur, aucun autre utilisateur ne peut accéder aux données du magasin. Les données ne sont toutefois pas protégées contre les accès par d’autres applications exécutées par un utilisateur authentifié. Puisque l’utilisateur doit être authentifié pour que ces attaques aboutissent, les données privées de ce dernier demeurent protégées, à moins que le compte utilisateur en tant que tel ne soit plus sécurisé. Toutefois, les données que votre application ne souhaite pas partager avec d’autres utilisateurs, telles que les clés d’obtention de licence ou de gestion des droits numériques, ne sont pas sécurisées. L’ESL n’est donc pas adapté au stockage d’informations de ce type. Il convient uniquement au stockage des données privées d’un utilisateur, telles que les mots de passe. Les données stockées dans l’ELS risquent d’être perdues pour diverses raisons. L’utilisateur pourrait par exemple désinstaller l’application et supprimer le fichier chiffré. L’identifiant d’éditeur pourrait également être modifié suite à une mise à jour. L’ELS doit de ce fait être traité comme une mémoire cache privée et non un emplacement de stockage de données permanent. L’utilisation du paramètre stronglyBound étant déconseillée, ne le définissez pas sur true. Définir ce paramètre sur true ne constitue pas une mesure de protection complémentaire des données. L’accès aux données est par ailleurs perdu lorsque l’application est mise à jour, même si l’identifiant d’éditeur ne change pas. Les performances du magasin local chiffré risquent d’être plus lentes si les données stockées dépassent 10 Mo. Lorsque vous désinstallez une application AIR, le programme de désinstallation ne supprime pas les données stockées dans le magasin local chiffré. Recommandations d’utilisation
• Intégrez dans l’application une technique de recréation des données stockées dans l’ELS en cas de perte des données stockées dans ce dernier. Vous pouvez, par exemple, inviter l’utilisateur à saisir à nouveau les informations d’identification du compte si besoin est.
• Si vous définissez stronglyBound sur true, n’effectuez pas la migration des éléments stockés lors d’une mise à jour. Créez à nouveau les données une fois la mise à jour terminée.
Les données sont stockées dans une table de hachage, dans laquelle les chaînes font office de clés et les données stockées de tableaux d’octets. Par exemple, le code suivant stocke une chaîne dans le magasin local chiffré : var str:String = "Bob"; var bytes:ByteArray = new ByteArray(); bytes.writeUTFBytes(str); EncryptedLocalStore.setItem("firstName", bytes);
EncryptedLocalStore.setItem("firstName", bytes, false); Remarque : en pratique, définir stronglyBound sur true n’assure aucune protection complémentaire des données. Un utilisateur « malveillant » pourrait en effet modifier une application en vue d’accéder aux éléments stockés dans l’ELS. Que stronglyBound soit défini sur true ou false, les données sont par ailleurs aussi bien protégées contre les menaces externes émanant de personnes autres que les utilisateurs. De ce fait, il est déconseillé de définir stronglyBoundsur true.
Adobe AIR 1.0 et les versions ultérieures Pour extraire une valeur du magasin local chiffré, utilisez la méthode EncryptedLocalStore.getItem(), comme dans l’exemple suivant : var storedValue:ByteArray = EncryptedLocalStore.getItem("firstName"); trace(storedValue.readUTFBytes(storedValue.length)); // "Bob"
Adobe AIR 1.0 et les versions ultérieures Pour supprimer une valeur du magasin local chiffré, utilisez la méthode EncryptedLocalStore.removeItem(), comme dans l’exemple suivant : EncryptedLocalStore.removeItem("firstName");
EncryptedLocalStore.reset(); Adobe AIR 1.0 et les versions ultérieures Pour obtenir une explication rapide de l’utilisation de bases de données SQL et des exemples de code correspondants, voir les articles de démarrage rapide suivants dans Adobe Developer Connection :
• Utilisation asynchrone d’une base de données SQL locale (Flex) • Utilisation d’une base de données chiffrée (Flex) Adobe AIR 1.0 et les versions ultérieures La fonctionnalité de base de données SQL locale de l’application AIR peut répondre à tout objectif de stockage des données d’application sur l’ordinateur local d’un utilisateur. Adobe AIR inclut plusieurs mécanismes de stockage local des données, chacun présentant des avantages distincts. Voici quelques utilisations possibles d’une base de données SQL locale dans votre application AIR :
Utilisation des bases de données SQL locales dans AIR
éventuellement à partager, chaque document peut être enregistré sous forme de fichier de base de données, à l’emplacement désigné par l’utilisateur. (Notez, toutefois, que si la base de données n’est pas chiffrée, toute application AIR peut ouvrir le fichier de bases de données. Le chiffrement est donc recommandé pour tous les documents potentiellement sensibles.)
Christophe Coenraets : Employee Directory on AIR for Android (disponible en anglais uniquement) Raymond Camden : jQuery and AIR - Moving from web page to application (disponible en anglais uniquement) Une base de données SQL locale Adobe AIR individuelle est stockée sous la forme d’un seul fichier dans le système de fichiers de l’ordinateur. Le moteur de base de données SQL du moteur d’exécution gère la création et le formatage des fichiers de base de données, de même que la manipulation et la récupération des données dans un fichier de base de données. Le moteur d’exécution ne spécifie pas comment ni où les données de la base de données sont stockées dans le système de fichiers, mais chaque base de données est stockée dans son intégralité dans un seul fichier. Vous spécifiez l’emplacement de stockage du fichier de base de données dans le système de fichiers. Une même application AIR peut accéder à une ou plusieurs bases de données distinctes (c’est-à-dire à des fichiers de base de données distincts). Le moteur d’exécution stockant chaque base de données sous forme d’un seul fichier dans le système de fichiers, vous pouvez localiser votre base de données selon vos besoins, en fonction de la conception de votre application et des contraintes d’accès aux fichiers du système d’exploitation. Chaque utilisateur peut disposer d’un fichier de base de données distinct pour ses données spécifiques, ou tous les utilisateurs de l’application peuvent accéder à un fichier de bases de données sur un ordinateur dans le cas de données partagées. Les données étant stockées localement sur un seul ordinateur, elles ne sont pas automatiquement partagées avec les utilisateurs d’autres ordinateurs. Le moteur de la base de données SQL locale ne permet pas d’exécuter des instructions SQL sur une base de données distante ou basée sur un serveur.
Adobe AIR 1.0 et les versions ultérieures Une base de données relationnelle est un mécanisme de stockage (et de récupération) des données sur un ordinateur. Les données sont organisées en tables : les lignes représentent les enregistrements ou les éléments, et les colonnes (parfois appelées « champs ») divisent chaque enregistrement en valeurs individuelles. Par exemple, une application de carnet d’adresses peut contenir une table nommée « amis ». Chaque ligue de la table représente alors un ami stocké dans la base de données. Les colonnes de cette table représentent des données telles que le prénom, le nom, la date de naissance, etc. Pour chaque ligne de la table, la base de données stocke une valeur distincte dans chaque colonne.
Outre le stockage des données de vos amis et de leurs numéros de téléphone, chaque table a besoin d’un élément de données qui lui permette de relier les deux tables (pour mettre en correspondance les enregistrements individuels des amis et leurs numéros de téléphone). Ces données sont appelées clé primaire (identifiant unique qui différencie chaque ligne de la table des autres lignes de cette même table). La clé primaire peut être une « clé naturelle », c’est-à-dire un élément de données qui différencie naturellement chaque enregistrement d’une table. Dans le cas de la table « amis », si vous savez qu’aucun de vos amis n’a la même date de naissance, vous pouvez utiliser la colonne date de naissance comme clé primaire (clé naturelle) de cette table. S’il n’existe pas de clé naturelle, vous pouvez créer une colonne de clé primaire distincte telle que « ID ami » (valeur artificielle utilisée par l’application pour différencier les lignes). L’utilisation d’une clé primaire permet de définir les relations existant entre plusieurs tables. Supposons par exemple que la colonne « ID ami » de la table « amis » contienne un numéro unique pour chaque ligne (chaque ami). La table reliée « numéros de téléphone » peut être structurée sur deux colonnes : l’une contenant l’identifiant de l’ami à qui le numéro de téléphone appartient, l’autre contenant le numéro de téléphone lui-même. Ainsi, quel que soit le nombre de numéros de téléphone d’un ami, tous peuvent être stockés dans la table « numéros de téléphone » et reliés à l’ami associé via la clé primaire « ID ami ». Lorsque la clé primaire d’une table est utilisée dans une table reliée pour spécifier la connexion entre les enregistrements, la valeur de la table reliée est appelée clé étrangère. Contrairement à de nombreuses bases de données, le moteur de base de données locale de l’application AIR ne vous permet pas de créer des contraintes de clé étrangère. Ces contraintes vérifient automatiquement qu’une valeur de clé étrangère mise à jour ou insérée correspond à une ligne de la table de clés primaires. Les relations entre les clés étrangères sont toutefois un élément important de la structure d’une base de données relationnelle, et les clés étrangères doivent être utilisées lors de la création de relations entre les tables de votre base de données.
Le langage SQL (Structured Query Language) est utilisé avec les bases de données relationnelles pour manipuler et récupérer les données. SQL est davantage un langage descriptif qu’un langage procédural. Au lieu de donner à l’ordinateur des instructions sur la façon dont les données doivent être récupérées, une instruction SQL décrit le jeu de données désiré. Le moteur de base de données détermine lui comment récupérer ces données. Le langage SQL a été normalisé par l’institut ANSI (American National Standards Institute). La base de données SQL locale d’Adobe AIR prend en charge la plupart des standards SQL-92. Pour consulter des descriptions spécifiques du langage SQL pris en charge dans Adobe AIR, voir « Prise en charge de SQL dans les bases de données locales » à la page 1154.
Pour travailler avec des bases de données SQL locales dans ActionScript 3.0, vous utilisez les occurrences des classes suivantes du package flash.data :
SQLColumnSchema.defaultCollationType et du paramètre defaultCollationType du constructeur SQLColumnSchema().
Définit un ensemble de constantes représentant les valeurs possibles de la propriété operation de la classe SQLError, indiquant l’opération de base de données ayant provoqué une erreur.
Adobe AIR 1.0 et les versions ultérieures Lorsque vous écrivez du code pour travailler avec une base de données SQL locale, vous spécifiez que les opérations de cette base de données doivent s’exécuter dans l’un des deux modes d’exécution suivants : asynchrone ou synchrone. En général, les exemples de code montrent comment effectuer chaque opération des deux manières. Vous pouvez donc utiliser l’exemple répondant le mieux à vos besoins. En mode d’exécution asynchrone, vous envoyez une instruction au moteur d’exécution et ce dernier distribue un événement lorsque l’opération demandée se termine ou échoue. Vous commencez par indiquer au moteur de base de données d’effectuer une opération. Celui-ci travaille en arrière-plan pendant que l’application poursuit son exécution. Enfin, lorsque l’opération est terminée (ou lorsqu’elle échoue), le moteur de base de données distribue un événement. Votre code, déclenché par l’événement, effectue les opérations consécutives. Cette approche présente un avantage important : le moteur d’exécution effectue les opérations de base de données en arrière-plan pendant que le code de l’application principale poursuit son exécution. Si l’opération de base de données prend un certain temps, l’exécution de l’application n’est pas interrompue. Plus important encore, l’utilisateur peut continuer à interagir avec elle sans que l’écran ne se fige. Toutefois, la rédaction du code d’opérations asynchrones peut se révéler plus complexe que la rédaction d’autres codes. Cette complexité survient généralement lorsque plusieurs opérations dépendantes doivent être réparties entre diverses méthodes d’écouteur d’événement. De façon conceptuelle, il est plus simple de coder les opérations sous forme d’une seule séquence d’étapes (ensemble d’opérations synchrones) plutôt que sous forme d’un ensemble d’opérations divisées en plusieurs méthodes d’écouteur d’événement. Outre les opérations de base de données asynchrones, Adobe AIR vous permet également d’exécuter des opérations de base de données de façon synchrone. Dans ce mode, les opérations ne s’exécutent pas en arrière-plan mais dans la même séquence d’exécution que le reste du code de l’application. Vous indiquez au moteur de base de données d’effectuer une opération. Le code s’interrompt alors à ce stade pendant que le moteur de base de données effectue son travail. Lorsque l’opération est terminée, l’exécution se poursuit avec la ligne suivante de votre code.
Si vous appelez SQLConnection.open(), la connexion opère en mode d’exécution synchrone, et si vous appelez SQLConnection.openAsync(), le mode d’exécution asynchrone est utilisé. Lorsqu’une occurrence de SQLConnection est connectée à une base de données à l’aide de open() ou openAsync(), elle est figée en mode d’exécution synchrone ou asynchrone, sauf si vous fermez et rouvrez la connexion à la base de données. Chaque mode d’exécution a ses propres avantages. Bien que similaires dans la plupart de leurs aspects, chaque mode présente des différences que vous devez connaître pour les exploiter correctement. Pour plus d’informations et pour obtenir des suggestions quant au choix de chaque mode, voir la section « Utilisation des opérations de base de données synchrones et asynchrones » à la page 782.
Adobe AIR 1.0 et les versions ultérieures Pour que votre application puisse ajouter ou récupérer des données, elle doit pouvoir accéder à une base de données avec des tables définies. Cette section décrit la création d’une base de données et de la structure de ses données. Bien que moins fréquemment utilisées que l’insertion et la récupération de données, ces tâches sont nécessaires pour la plupart des applications.
Mind the Flex : Updating an existing AIR database (disponible en anglais uniquement)
Le code suivant montre le processus de création d’un fichier de base de données (nouvelle base de données) en mode d’exécution asynchrone. Dans ce cas, le fichier de base de données est enregistré dans le « Pointage vers le répertoire de stockage d’une application » à la page 697, sous le nom « DBSample.db » :
Pour exécuter des opérations en mode synchrone, lorsque vous ouvrez une connexion à la base de données avec l’occurrence de SQLConnection, appelez la méthode open(). L’exemple suivant montre comment créer et ouvrir une occurrence de SQLConnection qui exécute ses opérations de façon synchrone :
La création d’une table dans une base de données implique l’exécution d’une instruction SQL sur cette base de données, selon la procédure utilisée pour exécuter une instruction SQL telle que SELECT, INSERT, etc. Pour créer une table, vous utilisez une instruction CREATE TABLE, qui inclut les définitions des colonnes et les contraintes de la nouvelle table. Pour plus d’informations sur l’exécution d’instructions SQL, voir la section « Utilisation des instructions SQL » à la page 757. L’exemple suivant montre la création d’une table nommée « employees » dans un fichier de base de données existant, en mode d’exécution asynchrone. Notez que ce code présuppose l’existence d’une occurrence de SQLConnection nommée conn, déjà instanciée et connectée à une base de données. import import import import
Adobe AIR 1.0 et les versions ultérieures Avant d’effectuer toute opération sur une base de données, commencez par ouvrir une connexion au fichier de cette base de données. Une occurrence de SQLConnection permet de représenter une connexion à une ou plusieurs bases de données. La première base de données connectée par une occurrence de SQLConnection est appelée base de données « principale ». Cette base de données est connectée par la méthode open() (en mode d’exécution synchrone) ou par la méthode openAsync() (en mode d’exécution asynchrone). Si vous ouvrez une base de données via l’opération asynchrone openAsync(), enregistrez l’événement open de l’occurrence de SQLConnection pour être averti(e) lorsque l’opération openAsync() se termine. Enregistrez l’événement error de l’occurrence de SQLConnection pour savoir si l’opération a échoué. L’exemple suivant montre comment ouvrir un fichier de base de données existant pour une exécution asynchrone. Le fichier de base de données est nommé « DBSample.db » et réside dans le « Pointage vers le répertoire de stockage d’une application » à la page 697. import import import import import
SQLMode.READ pour le paramètre openMode afin d’ouvrir une base de données existante en lecture seule. Dans ce cas, les données peuvent être récupérées dans la base de données, mais ne peuvent pas être ajoutées, supprimées ou modifiées.
Une instruction SQL individuelle (requête ou commande) est représentée dans le moteur d’exécution par un objet SQLStatement. Pour créer et exécuter une instruction SQL, procédez comme suit : Créez une occurrence de SQLStatement. L’objet SQLStatement représente l’instruction SQL dans votre application. var selectData:SQLStatement = new SQLStatement();
Pour ce faire, définissez la propriété sqlConnection de l’objet SQLStatement sur l’occurrence de SQLConnection connectée à la base de données désirée. // A SQLConnection named "conn" has been created previously selectData.sqlConnection = conn;
Créez le texte de l’instruction sous forme d’occurrence de String et affectez-la à la propriété text de l’occurrence de SQLStatement. selectData.text = "SELECT col1, col2 FROM my_table WHERE col1 = :param1";
Utilisez la méthode addEventListener() pour enregistrer les fonctions en tant qu’écouteurs des événements result et error de l’occurrence de SQLStatement. // using listener methods and addEventListener() selectData.addEventListener(SQLEvent.RESULT, resultHandler); selectData.addEventListener(SQLErrorEvent.ERROR, errorHandler); function resultHandler(event:SQLEvent):void { // do something after the statement execution succeeds « Récupération de données dans une base de données » à la page 761 « Insertion de données » à la page 771 « Modification ou suppression de données » à la page 777
Adobe AIR 1.0 et les versions ultérieures L’ajout d’un paramètre dans une instruction SQL permet de créer une instruction SQL réutilisable. Lorsque vous ajoutez des paramètres à une instruction, les valeurs de celle-ci peuvent changer (les valeurs ajoutées à une instruction INSERT, par exemple), mais le texte de base de l’instruction ne change pas. C’est pourquoi l’ajout de paramètres constitue un avantage en termes de performances et simplifie le codage des applications.
Il est fréquent qu’une application utilise plusieurs fois une même instruction SQL, avec de légères variations. Prenons par exemple le cas d’une application de suivi de stock qui permet à l’utilisateur d’ajouter de nouveaux articles dans la base de données. Le code de l’application qui ajoute un article de stock dans la base de données exécute une instruction SQL INSERT qui ajoute véritablement les données dans la base de données. Toutefois, chaque exécution de l’instruction présente une légère variation. En particulier, les véritables valeurs insérées dans la table diffèrent puisqu’elles sont spécifiques à l’article ajouté au stock. Lorsqu’une instruction SQL est utilisée plusieurs fois avec des valeurs différentes dans l’instruction, la meilleure approche consiste à utiliser une instruction SQL incluant des paramètres plutôt que des valeurs littérales dans le texte SQL. Un paramètre est un espace réservé dans le texte de l’instruction qui est remplacé par une valeur réelle à chaque exécution de l’instruction. Pour utiliser des paramètres dans une instruction SQL, vous créez une occurrence de SQLStatement standard. Dans le cas de la véritable instruction SQL affectée à la propriété text, utilisez des espaces réservés aux paramètres plutôt que des valeurs littérales. Définissez ensuite la valeur de chaque paramètre en définissant la valeur d’un élément dans la propriété parameters de l’occurrence de SQLStatement. La propriété parameters étant un tableau associatif, définissez une valeur déterminée à l’aide de la syntaxe suivante : statement.parameters[parameter_identifier] = value;
Adobe AIR 1.0 et les versions ultérieures Un paramètre peut être un paramètre nommé. Un paramètre nommé a un nom spécifique que la base de données utilise pour mettre en correspondance sa valeur avec l’emplacement de l’espace réservé dans le texte de l’instruction. Un nom de paramètre se compose du caractère « : » ou « @ » suivi d’un nom, comme dans les exemples suivants : :itemName @firstName
"INSERT INTO inventoryItems (name, productCode)" + "VALUES (?, ?)"; var addItemStmt:SQLStatement = new SQLStatement(); addItemStmt.sqlConnection = conn; addItemStmt.text = sql; // set parameter values addItemStmt.parameters[0] = "Item name"; addItemStmt.parameters[1] = "12345"; addItemStmt.execute(); Performances optimisées L’exécution d’une occurrence de SQLStatement avec paramètres est plus efficace que celle
Typage explicite des données Les paramètres autorisent la substitution avec type de valeurs inconnues au moment de
Pour plus d’informations sur les classes de stockage et l’affinité des colonnes, voir « Prise en charge des types de données » à la page 1177. Sécurité renforcée Les paramètres sont également utilisés comme mesure de sécurité pour prévenir toute technique malveillante appelée attaque par injection de code SQL. Dans une attaque par injection de code SQL, l’utilisateur entre du code SQL dans un emplacement accessible (par exemple dans un champ de saisie). Si le code de l’application construit une instruction SQL en concaténant directement la saisie de l’utilisateur dans le texte SQL, le code SQL saisi par l’utilisateur est exécuté sur la base de données. L’exemple suivant illustre la concaténation de la saisie de l’utilisateur dans le texte SQL. N’utilisez pas cette technique :
La récupération de données dans une base de données comprend deux étapes. Vous exécutez d’abord une instruction SQL SELECT, en décrivant le jeu de données désiré de la base de données. Vous accédez ensuite aux données récupérées et vous les affichez ou les manipulez selon les besoins de votre application.
Pour extraire des données existantes d’une base de données, utilisez une occurrence de SQLStatement. Affectez l’instruction SQL SELECT appropriée à la propriété text de l’occurrence, puis appelez sa méthode execute(). Pour plus d’informations sur la syntaxe de l’instruction SELECT, voir « Prise en charge de SQL dans les bases de données locales » à la page 1154. L’exemple suivant décrit l’exécution d’une instruction SELECT pour récupérer des données dans une table nommée « products », en mode d’exécution asynchrone :
Lorsque l’exécution de l’instruction SELECT est terminée, l’étape suivante consiste à accéder aux données récupérées. Pour récupérer les données du résultat de l’instruction SELECT exécutée, appelez la méthode getResult() de l’objet SQLStatement : var result:SQLResult = selectStatement.getResult();
{ Toute classe affectée en tant que propriété itemClass doit avoir un constructeur qui ne requiert aucun paramètre. En outre, la classe doit avoir une seule propriété pour chaque colonne renvoyée par l’instruction SELECT. Le fait qu’une colonne de la liste SELECT ne présente pas de nom de propriété correspondant dans la classe itemClass est considéré comme une erreur.
Par défaut, l’exécution d’une instruction SELECT récupère simultanément toutes les lignes du jeu de résultats. Une fois l’instruction terminée, vous traitez généralement les données récupérées d’une manière ou d’une autre, par exemple en créant des objets ou en affichant les données à l’écran. Si l’instruction renvoie un très grand nombre de lignes, le traitement simultané de toutes les données peut se révéler très exigeant pour l’ordinateur, qui à son tour peut ne pas redessiner l’interface pour l’utilisateur. Pour améliorer les performances de votre application, vous pouvez demander au moteur d’exécution de ne renvoyer simultanément qu’un nombre spécifique de lignes de résultats. Les données de résultats initiales sont ainsi renvoyées plus rapidement. Vous pouvez également diviser les lignes du résultat en jeux, de sorte que l’interface utilisateur soit mise à jour après le traitement de chaque jeu de lignes. Notez que cette technique n’est pratique qu’en mode d’exécution asynchrone. Pour récupérer les résultats partiels de SELECT, donnez une valeur au premier paramètre de la méthode SQLStatement.execute() (paramètre prefetch). Le paramètre prefetch indique le nombre de lignes à récupérer
SQLStatement, spécifiez la valeur du paramètre prefetch afin que seul ce nombre de lignes soit récupéré : var stmt:SQLStatement = new SQLStatement(); stmt.sqlConnection = conn; stmt.text = "SELECT ..."; stmt.addEventListener(SQLEvent.RESULT, selectResult); stmt.execute(20); // only the first 20 rows (or fewer) are returned
Insertion de données Adobe AIR 1.0 et les versions ultérieures L’ajout de données dans une base de données implique l’exécution d’une instruction SQL INSERT. Lorsque l’exécution de l’instruction est terminée, vous pouvez accéder à la clé primaire de la ligne nouvellement insérée si la base de données en a généré une.
Pour ajouter des données dans une table de base de données, créez et exécutez une occurrence de SQLStatement dont le texte est une instruction SQL INSERT. L’exemple suivant utilise une occurrence de SQLStatement pour ajouter une ligne de données dans la table des employés déjà existante. Cet exemple décrit l’insertion de données en mode d’exécution asynchrone. Notez que ce code présuppose l’existence d’une occurrence de SQLConnection nommée conn, déjà instanciée et connectée à une base de données. Il suppose également que la table « employees » a déjà été créée.
Après l’insertion d’une ligne de données dans une table, il arrive souvent que le code doive connaître la clé primaire générée par la base de données ou une valeur d’identificateur de ligne pour la ligne nouvellement insérée. Par exemple, après avoir inséré une ligne dans une table, vous pouvez en ajouter d’autres dans une table associée. Dans ce cas, vous pouvez insérer la valeur de la clé primaire en tant que clé étrangère de la table associée. La clé primaire d’une ligne nouvellement insérée peut être récupérée par le biais de l’objet SQLResult généré par l’instruction exécutée. Il s’agit du même objet qui est utilisé pour accéder aux données du résultat après l’exécution d’une instruction SELECT. Comme pour toute instruction SQL, lorsque l’exécution d’une instruction INSERT se termine, le moteur d’exécution crée une occurrence de SQLResult. Pour accéder à l’occurrence de SQLResult, vous appelez la méthode getResult() de l’objet
Dernière mise à jour le 27/4/2013
Modification ou suppression de données Adobe AIR 1.0 et les versions ultérieures La procédure d’exécution des autres opérations de manipulation des données est identique à celle utilisée pour exécuter une instruction SQL SELECT ou INSERT (voir « Utilisation des instructions SQL » à la page 757). Substituez simplement une autre instruction SQL dans la propriété text de l’occurrence de SQLStatement :
• Pour supprimer une ou plusieurs lignes de données dans une table, utilisez une instruction DELETE. Pour consulter une description de ces instructions, voir « Prise en charge de SQL dans les bases de données locales » à la page 1154.
Adobe AIR 1.0 et les versions ultérieures La méthode SQLConnection.attach() permet d’ouvrir une connexion à une autre base de données sur une occurrence de SQLConnection pour laquelle une base de données est déjà ouverte. Nommez la base de données reliée à l’aide du paramètre name dans l’appel de la méthode attach(). Lorsque vous écrivez des instructions pour manipuler cette base de données, vous pouvez alors utiliser ce nom dans un préfixe (sous la forme nom-base de données.nom-table) pour qualifier les noms de table dans vos instructions SQL, indiquant ainsi au moteur d’exécution que la table est disponible dans la base de données nommée. Vous pouvez exécuter une même instruction SQL incluant des tables de plusieurs bases de données connectées à la même occurrence de SQLConnection. Si une transaction est créée sur l’occurrence de SQLConnection, cette transaction s’applique à toutes les instructions SQL exécutées à l’aide de cette occurrence de SQLConnection. Cela est vrai quelle que soit la base de données reliée sur laquelle l’instruction s’exécute.
Gestion des erreurs de base de données Adobe AIR 1.0 et les versions ultérieures En général, la gestion des erreurs de base de données est similaire à celle des autres erreurs d’exécution. Il est préférable d’écrire du code préparé aux erreurs susceptibles de survenir, et de répondre aux erreurs plutôt que de laisser ce rôle au moteur d’exécution. De façon générale, les erreurs de base de données potentielles se divisent en trois catégories : les erreurs de connexion, les erreurs de syntaxe SQL et les erreurs de contrainte.
Adobe AIR 1.0 et les versions ultérieures La plupart des erreurs de base de données sont des erreurs de connexion et peuvent survenir durant n’importe quelle opération. Si certaines stratégies permettent d’éviter les erreurs de connexion, il est rarement simple de récupérer correctement d’une erreur de connexion si la base de données est une partie sensible de votre application. La plupart des erreurs de connexion sont liés aux interactions entre le moteur d’exécution et le système d’exploitation, le système de fichiers et le fichier de la base de données. Par exemple, une erreur de connexion se produit si l’utilisateur n’est pas autorisé à créer un fichier de base de données dans un emplacement particulier du système de fichiers. Les stratégies suivantes permettent d’éviter les erreurs de connexion : Utilisation de fichiers de base de données spécifiques aux utilisateurs Au lieu d’utiliser un seul fichier de base de données pour tous les utilisateurs de l’application sur un même ordinateur, donnez à chaque utilisateur son propre fichier de base de données. Ce fichier doit être situé dans un répertoire associé au compte de l’utilisateur. Par exemple, il peut être placé dans le répertoire de stockage de l’application, le dossier Mes documents de l’utilisateur, sur le bureau de celui-ci, etc. Prise en compte des différents types d’utilisateurs Testez votre application avec les différents types de comptes d’utilisateur, sur des systèmes d’exploitation différents. Ne supposez pas que l’utilisateur possède des privilèges d’administrateur sur l’ordinateur. De même, ne partez pas du principe que la personne qui a installé l’application est l’utilisateur qui l’exécute. Prise en compte des divers emplacements des fichiers Si vous autorisez l’utilisateur à spécifier l’emplacement
Si une erreur de connexion se produit, elle surviendra probablement lors de la première tentative de création ou d’ouverture de la base de données. Cela signifie que l’utilisateur ne peut effectuer aucune opération de base de données dans l’application. Pour certains types d’erreurs, par exemple les erreurs d’autorisation ou de lecture seule, une technique de récupération possible consiste à copier le fichier de base de données dans un emplacement différent.
Adobe AIR 1.0 et les versions ultérieures Une erreur de syntaxe se produit lorsque l’application tente d’exécuter une instruction SQL qui n’est pas correctement rédigée. Les instructions SQL de base de données locales étant créées sous forme de chaîne, la vérification de la syntaxe SQL au moment de la compilation n’est pas possible. Toutes les instructions SQL doivent être exécutées pour vérifier leur syntaxe. Pour éviter les erreurs de syntaxe SQL, utilisez les stratégies suivantes : Test approfondi de toutes les instructions SQL Si possible, testez vos instructions SQL séparément lors du développement de votre application avant de les coder sous forme de texte d’instruction dans le code de l’application. De plus, utilisez une approche de test de code telle que le test des unités pour créer un ensemble de tests vérifiant chaque option possible et chaque variation du code. Utilisation des paramètres d’instruction au lieu de la concaténation (création dynamique) de code SQL Le fait
Pour récupérer d’une erreur de syntaxe, une application a besoin de code complexe pour pouvoir examiner l’instruction SQL et en corriger la syntaxe. En respectant les stratégies précédentes, votre code peut identifier toute source potentielle d’erreur de syntaxe SQL au moment de l’exécution (par exemple la saisie de l’utilisateur dans une instruction). Pour récupérer d’une erreur de syntaxe, donnez des consignes à l’utilisateur. Indiquez-lui ce qu’il doit faire pour que l’instruction s’exécute correctement.
Adobe AIR 1.0 et les versions ultérieures Les erreurs de contrainte se produisent lorsqu’une instruction INSERT ou UPDATE tente d’ajouter des données dans une colonne. L’erreur survient si les nouvelles données ne respectent pas l’une des contraintes définies pour la table ou la colonne. L’ensemble des contraintes possibles comprend : Contrainte unique Indique que pour toutes les lignes d’une table, il ne peut pas y avoir de valeurs en double dans une colonne. Alternativement, lorsque plusieurs colonnes sont combinées dans une contrainte unique, la combinaison des valeurs de ces colonnes ne doit pas être dupliquée. En d’autres termes, pour la ou les colonnes uniques spécifiées, chaque ligne doit être distincte. Contrainte de clé primaire En termes de données autorisées et interdites par une contrainte, une contrainte de clé primaire est identique à une contrainte unique. Contrainte non nulle Spécifie qu’une colonne ne peut pas stocker de valeur NULL et, par conséquent, qu’elle doit avoir
Contrainte de vérification Permet de spécifier une contrainte arbitraire pour une ou plusieurs tables. La règle qui définit que la valeur d’une colonne doit être comprise entre certaines limites est une contrainte de vérification courante (par exemple que la valeur d’une colonne numérique doit être supérieure à 0). Un autre type courant de contrainte de vérification spécifie les relations entre les valeurs des colonnes (par exemple que la valeur d’une colonne doit être différente de la valeur d’une autre colonne pour la même ligne).
Pour plus d’informations, voir la section « Utilisation des types de données des bases de données » à la page 781.
Outre les types de contraintes prédéfinies, le moteur d’exécution SQL prend en charge l’utilisation de déclencheurs. Un déclencheur est semblable à un gestionnaire d’événement. Il s’agit d’un jeu d’instructions prédéfini qui est exécuté lorsqu’une certaine action se produit. Par exemple, un déclencheur peut être défini pour s’exécuter lorsque des données sont insérées ou supprimées dans une table particulière. Une utilisation possible d’un déclencheur consiste à examiner les modifications apportées aux données et à provoquer une erreur lorsque les conditions spécifiées ne sont pas satisfaites. Ainsi, un déclencheur peut avoir le même objectif qu’une contrainte, et les stratégies qui permettent d’éviter les erreurs et de récupérer à partir d’erreurs de contrainte s’appliquent également aux erreurs générées par les déclencheurs. Toutefois, l’identificateur des erreurs générées par les déclencheurs diffère de celui des erreurs de contrainte. L’ensemble des contraintes s’appliquant à une table particulière est déterminé lors de la conception d’une application. La conception soignée des contraintes simplifie la conception de l’application quand au fait d’éviter et de récupérer à partir d’erreurs de contrainte. Les erreurs de contrainte sont toutefois difficiles à prévoir et à éviter systématiquement. Les anticipations sont difficiles car les erreurs de contrainte n’apparaissent pas avant l’ajout de données dans l’application. Des erreurs de contraintes surviennent lorsque des données sont ajoutées dans une base de données après sa création. Ces erreurs sont souvent dues aux relations entre les nouvelles données et les données existantes dans la base de données. Les stratégies suivantes permettent d’éviter de nombreuses erreurs de contrainte : Planification rigoureuse des contraintes et de la structure de la base de données L’objectif des contraintes est d’imposer des règles d’application et de protéger l’intégrité des données de la base de données. Lorsque vous planifiez votre application, prévoyez la structure que doit avoir votre base de données pour prendre en charge cette application. Dans le cadre de ce processus, identifiez les règles devant s’appliquer à vos données, par exemple si certaines valeurs sont obligatoires, si une valeur est définie par défaut, si les valeurs en double sont autorisées, etc. Ces règles vous guident dans la définition des contraintes des bases de données. Définition explicite des noms des colonnes Il est possible d’écrire une instruction INSERT sans spécifier de façon
En nommant explicitement les colonnes dans lesquelles des valeurs doivent être insérées, vous pouvez autoriser des valeurs générées automatiquement, des colonnes avec des valeurs par défaut et des colonnes autorisant les valeurs NULL. Cela vous permet en outre de vous assurer qu’une valeur explicite est insérée dans toutes les colonnes NOT NULL. Utilisation de valeurs par défaut Chaque fois que vous spécifiez une contrainte NOT NULL pour une colonne, spécifiez autant que possible une valeur par défaut dans la définition de la colonne. Le code de l’application peut également fournir des valeurs par défaut. Par exemple, votre application peut vérifier si une variable String est null et lui affecter une valeur avant de l’utiliser pour définir une valeur de paramètre d’instruction. Validation des données saisies par l’utilisateur Vérifiez les données saisies par l’utilisateur en amont pour vous
évidemment, une contrainte UNIQUE est plus difficile à vérifier puisqu’elle demanderait l’exécution d’une requête SELECT pour déterminer si les données sont uniques. Utilisation de déclencheurs Vous pouvez écrire un déclencheur qui valide (et éventuellement remplace) les données
Pour plus d’informations, voir la section « ON CONFLICT (algorithmes de conflit) » dans « Prise en charge de SQL dans les bases de données locales » à la page 1154. Rédaction de commentaires de correction L’ensemble des contraintes susceptibles d’affecter une commande SQL
à choisir un autre nom. Une autre réponse possible consiste à autoriser l’utilisateur à consulter les informations relatives au produit portant le même nom.
Adobe AIR 1.0 et les versions ultérieures Lorsqu’une table est créée dans une base de données, l’instruction de création définit l’affinité, ou le type de données, pour chaque colonne de cette table. Bien que les déclarations d’affinité puissent être omises, il est préférable de déclarer explicitement l’affinité des colonnes dans vos instructions SQL CREATE TABLE. En règle générale, tout objet stocké dans une base de données par une instruction INSERT est renvoyé sous forme d’occurrence du même type de données lorsque vous exécutez une instruction SELECT. Toutefois, le type de données de la valeur récupérée peut différer selon l’affinité de la colonne de la base de données dans laquelle la valeur est stockée. Lorsqu’une valeur est stockée dans une colonne, si son type de données ne correspond pas à l’affinité de la colonne, la base de données tente de convertir cette valeur en fonction de cette affinité. Par exemple, si une colonne de base de données est déclarée avec une affinité NUMERIC, la base de données tente de convertir les données insérées en classe de stockage numérique (INTEGER ou REAL) avant de stocker les données. Si les données ne peuvent pas être converties, la base de données renvoie une erreur. Selon cette règle, si la chaîne « 12345 » est insérée dans une colonne NUMERIC, la base de données la convertit automatiquement en la valeur entière 12345 avant de la stocker dans la base de données. Lorsqu’elle est récupérée par une instruction SELECT, la valeur est renvoyée sous forme d’occurrence d’un type de données numérique (tel que Number) plutôt que sous la forme d’une occurrence de String. Le meilleur moyen d’éviter une conversion non désirable du type de données est de respecter deux règles. D’abord, définissez chaque colonne avec l’affinité correspondant au type de données à stocker. Ensuite, insérez uniquement les valeurs dont le type de données correspond à l’affinité définie. Le respect de ces règles présente deux avantages. Les données ne sont pas converties de façon imprévue lors de leur insertion (ce qui peut éventuellement en modifier le sens). De plus, lorsque vous récupérez les données, elles sont renvoyées avec leur type de données d’origine. Pour plus d’informations sur les types d’affinités de colonne disponibles et l’utilisation des types de données dans une instruction SQL, voir « Prise en charge des types de données » à la page 1177.
Les sections précédentes ont décrit les opérations de bases de données courantes, telles que la récupération, l’insertion, la mise à jour et la suppression de données, ainsi que la création d’un fichier de bases de données, de tables et d’autres objets dans une base de données. Les exemples montraient comment effectuer ces opérations de façon asynchrone et synchrone. Nous vous rappelons qu’en mode d’exécution asynchrone, vous demandez au moteur de base de données d’effectuer une opération. Celui-ci travaille ensuite en arrière-plan pendant que l’application poursuit son exécution. Lorsque l’opération est terminée, le moteur de base de données déclenche un événement pour vous le signaler. Le principal avantage de l’exécution asynchrone est que le moteur d’exécution effectue les opérations de base de données en arrièreplan pendant que l’application principale poursuit son exécution. Cela est d’autant plus précieux lorsque l’exécution de l’opération prend beaucoup de temps. D’un autre côté, les opérations en mode d’exécution synchrone ne s’exécutent pas en arrière-plan. Vous indiquez au moteur de base de données d’effectuer une opération. Le code s’interrompt à ce stade pendant que le moteur de base de données effectue son travail. Lorsque l’opération est terminée, l’exécution se poursuit avec la ligne suivante de votre code. Une seule connexion de base de données ne permet pas d’exécuter certaines opérations ou instructions de façon synchrone et d’autres de façon asynchrone. Vous précisez si une occurrence de SQLConnection s’exécute en mode synchrone ou asynchrone lors de l’ouverture de la connexion à la base de données. Si vous appelez SQLConnection.open(), la connexion opère en mode d’exécution synchrone, et si vous appelez SQLConnection.openAsync(), le mode d’exécution asynchrone est utilisé. Dès qu’une occurrence de SQLConnection est connectée à une base de données par une méthode open() ou openAsync(), elle fonctionne définitivement en mode synchrone ou asynchrone.
Adobe AIR 1.0 et les versions ultérieures Le code utilisé pour exécuter et répondre aux opérations en mode d’exécution synchrone et celui utilisé en mode exécution asynchrone ne présentent que peu de différences. Les principales différences entre les deux approches sont de deux types. Le premier est l’exécution d’une opération qui dépend d’une autre opération (telles que les lignes de résultat de SELECT ou la clé primaire d’une ligne ajoutée par une instruction INSERT). Le second type de différence est la gestion des erreurs.
Adobe AIR 1.0 et les versions ultérieures La principale différence entre une exécution synchrone et asynchrone est qu’en mode synchrone, la rédaction du code prend la forme d’une suite d’étapes. Par contre, dans le code asynchrone, vous enregistrez des écouteurs d’événement et vous répartissez souvent les opérations entre les méthodes des écouteurs. Lorsqu’une base de données est connectée en mode synchrone, vous pouvez exécuter successivement une série d’opérations de base de données dans un seul bloc de code. L’exemple suivant illustre cette technique :
En mode synchrone, vous n’écoutez pas un événement d’erreur pour déterminer si une opération a échoué. A l’inverse, vous renfermez le code susceptible de déclencher des erreurs dans un jeu de blocs try..catch..finally. Vous enveloppez le code rejetant l’erreur dans le bloc try. Vous écrivez les actions à effectuer en réponse à chaque type d’erreur dans des blocs catch distincts. Vous placez le code qui doit toujours s’exécuter, sans tenir compte de la réussite ou de l’échec (par exemple, la fermeture d’une connexion à la base de données devenue inutile) dans un bloc finally. L’exemple suivant démontre l’utilisation des blocs try..catch..finally pour la gestion des erreurs. Il développe l’exemple précédent en ajoutant du code de gestion d’erreur :
SQLStatement distincte pour chaque instruction SQL à exécuter, vous pouvez appeler la méthode execute() d’une occurrence de SQLStatement pendant l’exécution d’une autre sans provoquer d’erreur.
Lorsque vous créez une occurrence de SQLStatement et appelez sa méthode execute(), cette opération d’exécution d’instruction est ajoutée à la file d’attente de la connexion. Si aucune opération n’est en cours d’exécution sur cette occurrence de SQLConnection, l’exécution de l’instruction commence en arrière-plan. Supposons maintenant, que dans le même bloc de code, vous créiez une autre occurrence de SQLStatement et appeliez sa méthode execute(). Cette seconde opération d’exécution d’instruction est ajoutée à la file d’attente derrière la première instruction. Dès que l’exécution de la première instruction est terminée, le moteur d’exécution passe à la prochaine opération de la file d’attente. Le traitement des opérations successives de la file d’attente s’effectue en arrière-plan, même lorsque l’événement result de la première opération est déclenché dans le code de l’application principale. Le code suivant illustre cette technique : // Using asynchronous execution mode var stmt1:SQLStatement = new SQLStatement(); stmt1.sqlConnection = conn; // ... Set statement text and parameters, and register event listeners ... stmt1.execute(); // At this point stmt1's execute() operation is added to conn's execution queue. var stmt2:SQLStatement = new SQLStatement(); stmt2.sqlConnection = conn; Adobe AIR 1.5, AIR a la capacité de créer et de se connecter à des fichiers d’une base de données chiffrée. Lorsque vous utilisez une base de données chiffrée, l’application doit fournir la clé de chiffrement appropriée pour se connecter à cette base de données. Si la clé de chiffrement fournie n’est pas correcte (ou s’il n’y a pas de clé), l’application ne peut pas se connecter à la base de données. Elle ne peut donc pas lire les données de la base de données ni y écrire ou modifier des données. Pour utiliser une base de données chiffrée, vous devez la créer en tant que base de données chiffrée. Avec une base de données chiffrée existante, vous pouvez ouvrir une connexion à la base de données. Vous pouvez également modifier la clé de chiffrement d’une base de données chiffrée. Mises à part la création et la connexion aux bases de données chiffrées, les techniques de travail sont les mêmes que pour une base de données non chiffrée. En particulier, l’exécution des instructions SQL est identique, que la base de données soit chiffrée ou non.
Adobe AIR 1.5 et les versions ultérieures Le chiffrement se révèle très utile dès que vous souhaitez limiter l’accès aux informations stockées dans une base de données. Dans Adobe AIR, la fonction de chiffrement de base de données peut être utilisée dans plusieurs objectifs. Voici quelques exemples pour lesquels l’utilisation d’une base de données chiffrée peut être utile :
• Stockage d’application local de données privées synchronisées avec un serveur (données envoyées et chargées depuis le serveur)
Comprendre la raison pour laquelle vous souhaitez utiliser une base de données chiffrée vous permet de choisir l’architecture de votre application. Le chiffrement risque en particulier d’affecter la manière dont l’application crée, obtient et stocke la clé de chiffrement de la base de données. Pour plus d’informations sur ces considérations, voir « Considérations relatives à l’utilisation du chiffrement avec une base de données » à la page 791. Parallèlement à l’utilisation d’une base de données chiffrée, le magasin local chiffré permet également de préserver la confidentialité des données sensibles. Grâce au magasin local chiffré, vous stockez une valeur ByteArray unique avec une clé String. Seule l’application AIR qui stocke la valeur peut y accéder, et ceci uniquement sur l’ordinateur sur lequel elle est stockée. Avec le magasin local chiffré, il n’est pas nécessaire de créer votre propre clé de chiffrement. Pour ces raisons, le magasin local chiffré convient davantage au stockage aisé d’une seule valeur ou d’un ensemble de valeurs facilement encodé dans un objet ByteArray. Une base de données chiffrée convient mieux aux grands ensembles de données où l’interrogation et le stockage de données structurées sont souhaitables. Pour plus d’informations sur l’utilisation du magasin local chiffré, voir « Stockage local chiffré » à la page 737.
Pour utiliser une base de données chiffrée, son fichier doit être chiffré lors de sa création. Lorsqu’une base de données a été créée sans chiffrement, elle ne peut plus être chiffrée par la suite. De la même façon, une base de données chiffrée ne peut pas devenir non chiffrée. Si nécessaire, vous pouvez modifier la clé de chiffrement d’une base de données chiffrée. Pour plus d’informations, voir la section « Modification de la clé de chiffrement d’une base de données » à la page 790. Si votre base de données n’est pas chiffrée et que vous souhaitez utiliser le chiffrement de bases de données, vous pouvez créer une nouvelle base de données chiffrée, puis y copier la structure et les données des tables existantes. La création d’une base de données chiffrée est très similaire à la création d’une base de données non chiffrée, décrite à la section « Création d’une base de données » à la page 746. Vous commencez par créer une occurrence de SQLConnection représentant la connexion à la base de données. Vous créez la base de données en appelant la méthode open() ou openAsync() de l’objet SQLConnection, en spécifiant un fichier qui n’existe pas encore pour l’emplacement de la base de données. La seule différence lors de la création d’une base de données chiffrée est que vous fournissez une valeur au paramètre encryptionKey (cinquième paramètre de la méthode open() et sixième paramètre de la méthode openAsync()). Un objet ByteArray contenant exactement 16 octets constitue une valeur valide du paramètre encryptionKey. Les exemples suivants illustrent la création d’une base de données chiffrée. Pour plus de simplicité, la clé de chiffrement est codée en dur dans le code de l’application dans ces exemples. Toutefois, cette technique est fortement déconseillée car elle n’est pas sécurisée. var conn:SQLConnection = new SQLConnection(); var encryptionKey:ByteArray = new ByteArray(); encryptionKey.writeUTFBytes("Some16ByteString"); // This technique is not secure! // Create an encrypted database in asynchronous mode conn.openAsync(dbFile, SQLMode.CREATE, null, false, 1024, encryptionKey); // Create an encrypted database in synchronous mode conn.open(dbFile, SQLMode.CREATE, false, 1024, encryptionKey);
Génération et utilisation d’une clé de chiffrement » à la page 792.
Adobe AIR 1.5 et les versions ultérieures Comme la création d’une base de données chiffrée, la procédure qui permet d’ouvrir une connexion à une base de données chiffrée est la même que pour une base de données non chiffrée. Cette procédure est détaillée à la section « Connexion à une base de données » à la page 754. Vous faites appel à la méthode open() pour ouvrir une connexion en mode d’exécution synchrone, à la méthode openAsync() pour ouvrir une connexion en mode d’exécution asynchrone. La seule différence est que, pour ouvrir une base de données chiffrée, vous spécifiez la valeur correcte du paramètre encryptionKey (cinquième paramètre de la méthode open() et sixième paramètre de la méthode openAsync()).
L’exemple suivant décrit l’ouverture d’une base de données chiffrée en mode d’exécution asynchrone. Pour plus de simplicité, dans cet exemple, la clé de chiffrement est codée en dur dans le code de l’application. Toutefois, cette technique est fortement déconseillée car elle n’est pas sécurisée. import import import import import
Adobe AIR 1.5 et les versions ultérieures Vous pouvez modifier ultérieurement la clé de chiffrement d’une base de données chiffrée. Pour modifier la clé de chiffrement d’une base de données, commencez par ouvrir une connexion à la base de données en créant une occurrence de SQLConnection, puis appelez sa méthode open() ou openAsync(). Lorsque la connexion à la base de données est établie, appelez la méthode reencrypt() en transmettant la nouvelle clé de chiffrement en tant qu’argument. Comme la plupart des opérations de base de données, le comportement de la méthode reencrypt() varie selon si la connexion à la base de données utilise le mode d’exécution synchrone ou asynchrone. Si vous utilisez la méthode open() pour vous connecter à la base de données, l’opération reencrypt() s’exécute de façon synchrone. Lorsque l’opération est terminée, l’exécution se poursuit avec la ligne suivante du code : var newKey:ByteArray = new ByteArray(); // ... generate the new key and store it in newKey conn.reencrypt(newKey);
Considérations relatives à l’utilisation du chiffrement avec une base de données Adobe AIR 1.5 et les versions ultérieures La section « Utilisation d’une base de données chiffrée » à la page 787 présente plusieurs cas de figure pour lesquels l’utilisation d’une base de données chiffrée peut être nécessaire. À l’évidence, les besoins de confidentialité diffèrent selon les différents cas d’utilisation des applications (les scénarios présentés, ainsi que d’autres). L’architecture du chiffrement dans votre application joue un rôle important sur le contrôle de la confidentialité des données d’une base de données. Par exemple, si vous utilisez une base de données chiffrée pour assurer la confidentialité des données personnelles, même vis-à-vis des autres utilisateurs de l’ordinateur, la base de données de chaque utilisateur a besoin de sa propre clé de chiffrement. Pour une sécurité optimale, votre application peut générer la clé à partir d’un mot de passe saisi par l’utilisateur. Baser la clé de chiffrement sur un mot de passe permet d’être certain que les données demeurent inaccessibles, même si une autre personne utilise le compte de l’utilisateur sur l’ordinateur. À l’extrême opposé, supposons à présent que vous souhaitiez qu’un fichier de bases de données soit lisible par tout utilisateur de votre application, mais pas par les utilisateurs d’autres applications. Dans ce cas, chaque copie installée de l’application doit pouvoir accéder à une clé de chiffrement partagée. Vous pouvez concevoir votre application, et en particulier la technique utilisée pour générer la clé de chiffrement, en fonction du niveau de confidentialité désiré pour les données de l’application. Voici une liste de quelques suggestions de conception répondant à divers niveaux de confidentialité des données :
• Pour qu’un seul utilisateur puisse accéder à la base de données sur un seul ordinateur, générez la clé à partir d’un mot de passe et d’une valeur générée arbitrairement, appelée salt. Un exemple de cette technique est disponible à la section « Exemple : Génération et utilisation d’une clé de chiffrement » à la page 792. Voici d’autres considérations relatives à la sécurité qu’il est important de ne pas oublier lors de la conception d’une application utilisant une base de données chiffrée :
HTML) ou dans un format binaire facile à décompiler (dans le cas de contenu SWF). Le code source étant accessible, les deux éléments à ne pas oublier sont :
• Toujours partir du principe qu’un attaquant peut aisément découvrir la technique utilisée pour générer une clé de chiffrement (par exemple un générateur de caractères aléatoire ou un algorithme de hachage particulier)
CBC-MAC (CCM). Pour être sécurisé, ce chiffrement combine la clé saisie par l’utilisateur avec une valeur salt. Un exemple de cette technique est disponible à la section « Exemple : Génération et utilisation d’une clé de chiffrement » à la page 792.
Adobe AIR 1.5 et les versions ultérieures Cet exemple d’application présente une technique de génération de clé de chiffrement. Cette application est conçue pour assurer le plus haut niveau de confidentialité et de sécurité aux données des utilisateurs. Un point essentiel de la sécurisation des données privées consiste à obliger l’utilisateur à saisir un mot de passe à chaque connexion de l’application à la base de données. Par conséquent, comme nous l’avons vu dans cet exemple, une application exigeant ce niveau de confidentialité ne doit jamais stocker directement la clé de chiffrement de la base de données. L’application comprend deux parties : une classe ActionScript qui génère une clé de chiffrement (la classe EncryptionKeyGenerator) et une interface utilisateur de base qui décrit l’utilisation de cette classe. Pour obtenir le code source complet, voir la section « Exemple de code complet pour la génération et l’utilisation d’une clé de chiffrement » à la page 795.
Il n’est pas nécessaire de maîtriser les détails du fonctionnement de la classe EncryptionKeyGenerator pour l’utiliser dans votre application. Si vous souhaitez savoir comment la classe génère une clé de chiffrement pour une base de données, voir « Fonctionnement de la classe EncryptionKeyGenerator » à la page 799. Pour utiliser la classe EncryptionKeyGenerator dans votre application, procédez comme suit : 1 Téléchargez la classe EncryptionKeyGenerator en tant que code source ou SWC compilé. La classe
(as3corelib). Vous pouvez télécharger le package as3corelib comprenant le code source et la documentation. Vous pouvez également télécharger des fichiers du code source ou SWC depuis la page du projet. 2 Placez le code source de la classe EncryptionKeyGenerator (ou le fichier SWC as3corelib) dans un emplacement
3 Dans le code source de votre application, ajoutez une instruction import pour la classe EncryptionKeyGenerator. import com.adobe.air.crypto.EncryptionKeyGenerator;
La méthode getEncryptionKey() génère et renvoie la clé de chiffrement (objet ByteArray à 16 octets). Vous pouvez alors utiliser la clé de chiffrement pour créer votre nouvelle base des données chiffrée ou ouvrir une base de données existante. La méthode getEncryptionKey() a un paramètre obligatoire, le mot de passe obtenu à l’étape 5.
à celle-ci. La méthode getEncryptionKey() accepte également un second paramètre (facultatif) overrideSaltELSKey. L’occurrence de EncryptionKeyGenerator crée une valeur aléatoire (appelée valeur salt) qui fait partie de la clé de chiffrement. Pour pouvoir recréer la clé de chiffrement, la valeur salt est stockée dans le magasin local chiffré (ELS) de votre application AIR. Par défaut, la classe EncryptionKeyGenerator utilise une chaîne particulière en tant que clé ELS. Bien que cela soit improbable, il est possible que cette clé soit en conflit avec une autre clé utilisée par votre application. Au lieu d’utiliser la clé par défaut, vous pouvez spécifier votre propre clé ELS. Dans ce cas, spécifiez une clé personnalisée en la transmettant en tant que second paramètre getEncryptionKey(), comme illustré ici : var customKey:String = "My custom ELS salt key"; var encryptionKey:ByteArray = keyGenerator.getEncryptionKey(password, customKey);
Dans cet exemple, l’application est conçue pour ouvrir la base de données en mode d’exécution asynchrone. Le code configure les écouteurs d’événement appropriés et appelle la méthode openAsync(), en transmettant la clé de chiffrement en tant qu’argument final : conn.addEventListener(SQLEvent.OPEN, openHandler); conn.addEventListener(SQLErrorEvent.ERROR, openError); conn.openAsync(dbFile, SQLMode.CREATE, null, false, 1024, encryptionKey);
à une base de données existante) et si l’ID d’erreur correspond à la constante EncryptionKeyGenerator.ENCRYPTED_DB_PASSWORD_ERROR_ID. Si ces deux conditions sont vraies, il est probable que le mot de passe saisi par l’utilisateur soit incorrect. (Cela peut également signifier que le fichier spécifié n’est pas un fichier de base de données.) Voici le code qui vérifie l’ID d’erreur : if (!createNewDB && event.error.errorID == EncryptionKeyGenerator.ENCRYPTED_DB_PASSWORD_ERROR_ID) { statusMsg.text = "Incorrect password!"; } else L’exemple utilise la classe EncryptionKeyGenerator pour créer une clé de chiffrement à partir d’un mot de passe. La classe EncryptionKeyGenerator est incluse dans le projet de bibliothèque centrale Open Source ActionScript 3.0 (as3corelib). Vous pouvez télécharger le package as3corelib comprenant le code source et la documentation. Vous pouvez également télécharger des fichiers du code source ou SWC depuis la page du projet. Exemple Flex Le fichier MXML de l’application contient le code source d’une application simple qui crée ou ouvre une connexion à une base de données chiffrée : <?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical" creationComplete="init();"> Il n’est pas nécessaire de comprendre le fonctionnement intrinsèque de la classe EncryptionKeyGenerator pour l’utiliser afin de créer une clé de chiffrement sécurisée pour la base de données de votre application. Le processus d’utilisation de la classe est décrit à la section « Utilisation de la classe EncryptionKeyGenerator pour obtenir une clé de chiffrement sécurisée » à la page 793. Il peut cependant se révéler précieux pour comprendre les techniques utilisées par la classe. Par exemple, vous pourriez vouloir adapter la classe ou intégrer certaines de ses techniques lorsqu’un niveau différent de confidentialité des données est nécessaire. La classe EncryptionKeyGenerator est incluse dans le projet de bibliothèque centrale Open Source ActionScript 3.0 (as3corelib). Vous pouvez télécharger le package as3corelib comprenant le code source et la documentation. Vous pouvez également afficher le code source dans le site du projet ou le télécharger pour suivre les explications.
Adobe AIR 1.5 et les versions ultérieures Lorsque le code appelle la méthode getEncryptionKey(), il transmet un mot de passe sous forme de paramètre. Ce mot de passe est utilisé comme base de la clé de chiffrement. En utilisant des informations que seul l’utilisateur connaît, cette technique permet de s’assurer que seul l’utilisateur qui connaît le mot de passe peut accéder au contenu de la base de données. Même s’il accède au compte de l’utilisateur sur l’ordinateur, l’attaquant ne peut pas accéder à la base de données sans connaître le mot de passe. Pour une sécurité maximale, l’application ne stocke jamais le mot de passe. Le code d’une application crée une occurrence d’EncryptionKeyGenerator et appelle la méthode getEncryptionKey() correspondante en transmettant un mot de passe saisi par l’utilisateur sous forme d’argument (soit la variable password dans cet exemple) : var keyGenerator:EncryptionKeyGenerator = new EncryptionKeyGenerator(); var encryptionKey:ByteArray = keyGenerator.getEncryptionKey(password);
L’expression régulière qui vérifie ce modèle est définie en tant que constante nommée STRONG_PASSWORD_PATTERN : private static const STRONG_PASSWORD_PATTERN:RegExp = /(?=^.{8,32}$)((?=.*\d)|(?=.*\W+))(?![.\n])(?=.*[A-Z])(?=.*[a-z]).*$/;
EncryptionKeyGenerator. Le code se présente comme suit : public function vaidateStrongPassword(password:String):Boolean { if (password == null || password.length <= 0) { return false; } return STRONG_PASSWORD_PATTERN.test(password)) Extension du mot de passe à 256 bits Adobe AIR 1.5 et les versions ultérieures Dans la suite du processus, le mot de passe doit avoir une longueur de 256 bits. Plutôt que de demander à chaque utilisateur de saisir un mot de passe faisant exactement 256 bits (32 caractères), le code crée un mot de passe plus long en répétant ses caractères.
L’étape suivante consiste à obtenir une valeur salt de 256 bits qui sera ensuite combinée au mot de passe dans une étape ultérieure. Une valeur salt est une valeur aléatoire ajoutée ou combinée à la valeur saisie par l’utilisateur pour composer le mot de passe. L’utilisation d’une valeur salt avec un mot de passe permet de s’assurer que, même si l’utilisateur choisit un mot du dictionnaire ou un terme courant comme mot de passe, la combinaison mot de passe-plus-salt utilisée par le système est une valeur aléatoire. Cet aspect aléatoire assure une protection contre les attaques de type dictionnaire, dans lesquelles l’attaquant utilise une liste de mots pour tenter de deviner le mot de passe. De plus, la génération de cette valeur salt et son stockage dans le magasin local chiffré permet de l’associer au compte de l’utilisateur sur l’ordinateur dans lequel le fichier de base de données est situé. Si l’application appelle la méthode getEncryptionKey() pour la première fois, le code crée une valeur salt aléatoire de 256 bits. Sinon, le code récupère la valeur salt dans le magasin local chiffré. La valeur salt est stockée dans une variable nommée salt. Le code détermine si une valeur salt a déjà été créée en tentant de la récupérer dans le magasin local chiffré :
EncryptionKeyGenerator utilise une clé prédéfinie du magasin local chiffré qui est définie dans la constante SALT_ELS_KEY. Au lieu d’utiliser la clé par défaut, le code de l’application peut également spécifier la clé de magasin local chiffré à utiliser dans l’appel à la méthode getEncryptionKey(). La clé de magasin local chiffré de la valeur salt par défaut ou spécifiée par l’application est stockée dans une variable nommée saltKey. Cette variable est utilisée dans les appels de EncryptedLocalStore.setItem() et EncryptedLocalStore.getItem(), comme indiqué précédemment. Combinaison du mot de passe 256 bits et de la valeur salt via l’opérateur XOR Adobe AIR 1.5 et les versions ultérieures Le code dispose à présent d’un mot de passe de 256 bits et d’une valeur salt de 256 bits. Il utilise ensuite une opération XOR au niveau du bit pour combiner la valeur salt avec le mot de passe concaténé dans une valeur unique. Cette technique crée un mot de passe de 256 bits à partir de tous les caractères possibles de la plage complète. Ce principe reste vrai même si la saisie du véritable mot de passe est plus probablement constituée des principaux caractères alphanumériques. Cet aspect encore plus aléatoire a l’avantage de créer le plus vaste ensemble possible de mots de passe sans que l’utilisateur ne doive lui-même saisir un mot de passe long et complexe. Le résultat de l’opération XOR est stocké dans la variable unhashedKey. La véritable opération XOR au niveau du bit sur les deux valeurs se produit dans la méthode xorBytes() : var unhashedKey:ByteArray = xorBytes(concatenatedPassword, salt);
Une fois le mot de passe concaténé et la valeur salt combinée, l’étape suivante consiste à sécuriser encore davantage cette valeur en la hachant avec un algorithme SHA-256. Le hachage de la valeur rend encore plus difficile sa rétroconception par un attaquant. À ce stade, le code possède un objet ByteArray nommé unhashedKey contenant le mot de passe concaténé combiné à la valeur salt. Le projet de bibliothèque ActionScript 3.0 (as3corelib) comprend une classe SHA256 dans le package com.adobe.crypto. La méthode SHA256.hashBytes() qui exécute un hachage SHA-256 sur l’objet ByteArray et renvoie une valeur String contenant le résultat du hachage 256 bits sous forme de nombre hexadécimal. La classe EncryptionKeyGenerator utilise la classe SHA256 pour hacher la clé : var hashedKey:String = SHA256.hashBytes(unhashedKey);
Adobe AIR 1.5 et les versions ultérieures La clé de chiffrement doit être un objet ByteArray faisant exactement 16 octets (128 bits). Le résultat de l’algorithme de hachage SHA-256 fait toujours 256 bits. Par conséquent, l’étape finale consiste à sélectionner 128 bits dans le résultat haché et à les utiliser comme véritable clé de chiffrement. Dans la classe EncryptionKeyGenerator, le code réduit la clé à 128 bits en appelant la méthode generateEncryptionKey(). Il renvoie ensuite le résultat de cette méthode en tant que résultat de la méthode getEncryptionKey() : var encryptionKey:ByteArray = generateEncryptionKey(hashedKey); return encryptionKey;
L’important est que le code sélectionne 128 bits distincts, et que ces mêmes 128 bits soient utilisés chaque fois. Dans ce cas, la méthode generateEncryptionKey() utilise la plage de bits commençant au 18ème octet en tant que clé de chiffrement. Comme nous l’avons déjà mentionné, la classe SHA256 renvoie une valeur String contenant un hachage 256 bits sous forme de nombre hexadécimal. Un unique bloc de 128 bits comprend trop d’octets pour qu’ils soient ajoutés en une seule fois à un objet ByteArray. Par conséquent, le code utilise une boucle for pour extraire les caractères de la valeur String hexadécimale, les convertit en valeurs numériques réelles et les ajoute à l’objet ByteArray. La valeur String SHA-256 résultante comprend 64 caractères. Une plage de 128 bits correspond à 32 caractères dans la valeur String et chaque caractère représente 4 bits. Le plus petit incrément de données que vous pouvez ajouter à un objet ByteArray correspond à un seul octet (8 bits), ce qui équivaut à deux caractères dans la valeur String hash. De ce fait, la boucle compte de 0 à 31 (32 caractères) par incréments de 2 caractères.
également avoir un impact sur le bon fonctionnement de l’application du point de vue des utilisateurs.
Adobe AIR 1.0 et les versions ultérieures Lorsque vous utilisez une base de données SQL locale AIR dans votre application, cette dernière attend une base de données présentant une certaine structure de tables, de colonnes, etc. Certaines applications s’attendent également à ce que certaines données soient pré-renseignées dans le fichier de la base de données. Créer la base de données au sein du code de l’application est un moyen de s’assurer que la base de données présente la structure appropriée. Lors du chargement de l’application, celle-ci vérifie la présence de son fichier de base de données dans un emplacement particulier. Si le fichier n’existe pas, l’application exécute un ensemble de commandes pour le créer, crée la structure de la base de données et renseigne les tables avec les données initiales. Le code qui crée la base de données et ses tables est souvent complexe. Bien souvent, il n’est utilisé qu’une fois au début de la durée de vie d’une application installée, mais augmente tout de même la taille et la complexité de celle-ci. Au lieu de créer la base de données, sa structure et ses données par programmation, vous pouvez distribuer une base de données pré renseignée avec votre application. Pour distribuer une base de données prédéfinie, incluez le fichier de base de données dans le package AIR de l’application.
Voici une liste de techniques conseillées qui permettront d’améliorer les performances, la sécurité et la simplicité de maintenance des applications lors de l’utilisation de bases de données SQL locales.
Adobe AIR 1.0 et les versions ultérieures Même si votre application n’exécute aucune instruction lors de son premier chargement, instanciez un objet SQLConnection et appelez sa méthode open() ou openAsync() en amont (par exemple après le démarrage initial de l’application) pour éviter les délais lors de l’exécution des instructions. Voir la section « Connexion à une base de données » à la page 754.
Adobe AIR 1.0 et les versions ultérieures Si vous accédez à une certaine base de données pendant l’exécution de votre application, gardez une référence à l’occurrence de SQLConnection et réutilisez-la dans toute l’application au lieu de fermer et de rouvrir la connexion. Voir la section « Connexion à une base de données » à la page 754.
Adobe AIR 1.0 et les versions ultérieures Lors de l’écriture du code d’accès aux données, il peut être tentant d’exécuter les opérations de façon synchrone plutôt que de façon asynchrone car cela demande souvent un code plus court et moins complexe. Toutefois, comme nous l’avons vu à la section « Utilisation des opérations de base de données synchrones et asynchrones » à la page 782, les opérations synchrones peuvent affecter les performances de façon évidente pour les utilisateurs et nuire à leur exploitation de l’application. Le temps nécessaire à l’exécution d’une seule opération varie d’une opération à l’autre et notamment en fonction de la quantité de données impliquées. Par exemple, une instruction SQL INSERT qui n’ajoute qu’une seule ligne à la base de données prend moins de temps qu’une instruction SELECT qui récupère des milliers de lignes de données. Toutefois, lorsque vous utilisez le mode synchrone pour exécuter plusieurs opérations, les opérations sont généralement enchaînées. Même si le temps nécessaire à chaque opération est très court, l’application se bloque jusqu’à ce que toutes les opérations synchrones soient terminées. En résultat, le temps cumulé des différentes opérations peut être suffisant pour bloquer votre application. Utilisez les opérations asynchrones comme approche habituelle, en particulier dans le cas d’opérations impliquant un grand nombre de lignes. Une technique permet de diviser le traitement des vastes jeux de résultats de l’instruction SELECT. Cette technique est décrite à la section « Récupération partielle des résultats d’une instruction SELECT » à la page 770. Cette technique ne peut cependant être utilisée qu’en mode d’exécution asynchrone. Utilisez uniquement les opérations synchrones lorsque vous ne pouvez pas obtenir certaines fonctionnalités avec la programmation
Dans la plupart des cas, l’utilisation d’une occurrence de SQLStatement distincte pour chaque instruction SQL à exécuter permet de mettre plusieurs opérations SQL en file d’attente à la fois, ce qui, en termes d’écriture du code, rend le code asynchrone similaire au code synchrone. Pour plus d’informations, voir la section « Présentation du modèle d’exécution asynchrone » à la page 785.
Adobe AIR 1.0 et les versions ultérieures Pour chaque instruction SQL exécutée plusieurs fois dans une application, créez une occurrence de SQLStatement distincte. Servez-vous de cette occurrence de SQLStatement chaque fois que cette commande SQL s’exécute. Supposons par exemple que vous développiez une application comprenant quatre opérations SQL différentes exécutées à plusieurs reprises. Dans ce cas, créez quatre occurrences de SQLStatement distinctes et appelez la méthode execute() de chaque instruction pour l’exécuter. Evitez d’utiliser une seule occurrence de SQLStatement pour toutes les instructions SQL, en redéfinissant chaque fois sa propriété text avant d’exécuter l’instruction.
Adobe AIR 1.0 et les versions ultérieures Utilisez des paramètres pour SQLStatement. Ne concaténez jamais la saisie de l’utilisateur dans le texte de l’instruction. L’utilisation de paramètres sécurise votre application car elle empêche les attaques par injection de code SQL. Il est alors possible d’utiliser des objets dans les requêtes (au lieu d’utiliser uniquement des valeurs littérales SQL). Cela renforce également l’efficacité de l’exécution des instructions car ces dernières peuvent être réutilisées sans qu’il soit nécessaire de les recompiler chaque fois qu’elles sont exécutées. Voir la section « Utilisation de paramètres dans des instructions » à la page 758.
Etant donné que les données informatiques se composent d’octets ou de groupes de 8 bits, la capacité de lire des données en octets implique qu’il est possible d’accéder à des données pour lesquelles aucune classe et aucune méthode d’accès n’existent. La classe ByteArray vous permet d’analyser tous les flux de données (d’une image bitmap à un flux de données transitant par le réseau) au niveau de l’octet. La méthode writeObject() vous permet d’écrire un objet au format AMF (Action Message Format) sérialisé dans une classe ByteArray, tandis que la méthode readObject() vous donne la possibilité de lire un objet sérialisé à partir d’une classe ByteArray vers une variable du type de données d’origine. Vous avez la possibilité de sérialiser n’importe quel objet, à l’exception des objets d’affichage, lesquels peuvent être placés dans la liste d’affichage. Vous pouvez également réaffecter des objets sérialisés à des occurrences d’une classe personnalisée si celle-ci est disponible pour le moteur d’exécution. Une fois qu’un objet a été converti au format AMF, vous pouvez le transférer rapidement par le biais d’une connexion réseau ou l’enregistrer dans un fichier. L’application Adobe® AIR® décrite dans cet exemple lit un fichier .zip pour illustrer le traitement d’un flux d’octets. Elle extrait une liste des fichiers contenus dans le fichier .zip et les écrit dans le poste de travail.
Spécification AMF (Action Message Format) Dernière mise à jour le 27/4/2013
Utilisation de tableaux d’octets
Par exemple, le code suivant lit un simple tableau de chaînes et de nombres à virgule flottante, puis écrit chaque élément vers un objet ByteArray. La structure du tableau permet au code d’appeler les méthodes ByteArray appropriées (writeUTFBytes() et writeFloat()) afin d’écrire les données. Le modèle de données répétitif permet de lire le tableau au moyen d’une boucle. // The following example reads a simple Array (groceries), made up of strings // and floating-point numbers, and writes it to a ByteArray. import flash.utils.ByteArray; // define the grocery list Array var groceries:Array = ["milk", 4.50, "soup", 1.79, "eggs", 3.19, "bread" , 2.35] Les propriétés length et bytesAvailable vous indiquent la longueur d’une classe ByteArray et le nombre d’octets restants entre la position active et la fin. L’exemple suivant illustre des modes d’utilisation de ces propriétés. L’exemple écrit une chaîne de texte dans la classe ByteArray, puis lit la classe ByteArray octet par octet jusqu’à la détection du caractère « a » ou l’arrivée au terme (bytesAvailable <= 0). var bytes:ByteArray = new ByteArray(); var text:String = "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Vivamus etc."; bytes.writeUTFBytes(text); // write the text to the ByteArray trace("The length of the ByteArray is: " + bytes.length);// 70 bytes.position = 0; // reset position while (bytes.bytesAvailable > 0 && (bytes.readUTFBytes(1) != 'a')) { //read to letter a or end of bytes } if (bytes.position < bytes.bytesAvailable) { trace("Found the letter a; position is: " + bytes.position); // 23 trace("and the number of bytes available is: " + bytes.bytesAvailable);// 47 Dernière mise à jour le 27/4/2013
Méthodes compress() et uncompress() Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La méthode compress() vous permet de compresser une classe ByteArray conformément à un algorithme de compression spécifié sous forme de paramètre. La méthode uncompress() vous permet de décompresser un tableau ByteArray compressé conformément à un algorithme de compression. Une fois que vous avez appelé compress() et uncompress(), la longueur du tableau d’octets est fixée selon la nouvelle longueur et la propriété position est configurée sur la fin. La classe CompressionAlgorithm définit des constantes pouvant servir à spécifier l'algorithme de compression. La classe ByteArray prend en charge les algorithmes deflate (AIR uniquement), zlib, et lzma. Le format de données compressé zlib est décrit à l’adresse http://www.ietf.org/rfc/rfc1950.txt. L’algorithme lzma a été ajouté à Flash Player 11.4 et AIR 3.4. Il est décrit sur la page suivante : http://www.7-zip.org/7z.html. L’algorithme de compression deflate est utilisé dans plusieurs formats de compression tels que zlib, gzip et certaines implémentations zip. L’algorithme de compression deflate est décrit à l’adresse http://www.ietf.org/rfc/rfc1951.txt. Dans l’exemple suivant, un tableau ByteArray appelé bytes est compressé à l’aide de l’algorithme Izma : bytes.compress(CompressionAlgorithm.LZMA);
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les méthodes readObject() et writeObject() permettent de lire un objet à partir d’une classe ByteArray et d’en écrire un dans une telle classe. Cet objet est codé au format AMF sérialisé. AMF est un protocole de message propriétaire créé par Adobe et utilisé par différentes classes ActionScript 3.0, notamment les objets Netstream, NetConnection, NetStream, LocalConnection et Shared.
Il existe deux versions du format AMF : AMF0 et AMF3. AMF 0 prend en charge l’envoi d’objets complexes par référence et permet aux points de fin de restaurer les relations entre objets. AMF 3 améliore le format AMF 0 en envoyant les traits et chaînes de l’objet par référence, en plus des références d’objet, et en prenant en charge de nouveaux types de données introduits dans la version 3.0 d’ActionScript. La propriété ByteArray.objectEcoding spécifie la version du format AMF utilisée pour coder les données d’objet. La classe flash.net.ObjectEncoding définit des constantes permettant de préciser la version du format AMF : ObjectEncoding.AMF0 et ObjectEncoding.AMF3. Dans l’exemple suivant, writeObject() est appelé pour écrire un objet XML dans une classe ByteArray, qu’il compresse ensuite à l’aide de l’algorithme Deflate et écrit dans le fichier order situé dans le poste de travail. Dans cet exemple, une étiquette affiche le message « Wrote order file to desktop! » (Fichier d’ordre écrit dans le poste de travail) dans la fenêtre d’AIR lorsque l’opération est terminée. import flash.filesystem.*; import flash.display.Sprite; import flash.display.TextField; import flash.utils.ByteArray; public class WriteObjectExample extends Sprite { public function WriteObjectExample() { var bytes:ByteArray = new ByteArray(); var myLabel:TextField = new TextField(); myLabel.x = 150; myLabel.y = 150; myLabel.width = 200; addChild(myLabel); var myXML:XML = <order> XML orderXML. Dans cet exemple, une construction de boucle for each() est utilisée pour ajouter chaque nœud à une zone de texte à des fins d’affichage. L’exemple présente également la valeur de la propriété objectEncoding accompagnée d’un en-tête pour le contenu du fichier order. import import import import
Le code présenté dans cet exemple a été rédigé dans le seul objectif d’analyser des fichiers zip ne contenant pas de dossiers ; il n’attend pas d’enregistrements de descripteurs de données. Il ne tient pas compte des informations suivant les données du dernier fichier. Le format de l’en-tête de fichier de chaque fichier est défini de la manière suivante : signature de l’en-tête de fichier
DEFLATE. Si le fichier actif est compressé à l’aide de la méthode de compression DEFLATE, compMethod est égal à 8 ; si le fichier n’est pas compressé, compMethod est égal à 0. bytes.position = 8; compMethod = bytes.readByte();
éventuellement, un champ supplémentaire. La variable offset stocke la taille de cette partie. La taille est calculée en ajoutant la longueur du nom de fichier à la longueur du champ supplémentaire, lue à partir de l’en-tête aux décalages 26 et 28. offset = 0;// stores length of variable portion of metadata bytes.position = 26; // offset to file name length flNameLength = bytes.readShort();// store file name offset += flNameLength; // add length of file name bytes.position = 28;// offset to extra field length xfldLength = bytes.readShort(); offset += xfldLength;// add length of extra field
// read variable length bytes between fixed-length header and compressed file data zStream.readBytes(bytes, 30, offset); à l’exception de la méthode outFile(). L’exécution revient au début de la boucle while et poursuit le traitement des octets suivants du fichier .zip, soit en extrayant un autre fichier soit en mettant un terme au traitement du fichier .zip si le dernier fichier a été traité. } // end of while loop } // for Flex version, end of init() method and application
Lorsque vous créez des applications dans Flash Player ou AIR, il est souvent nécessaire d’accéder à des ressources externes. Vous pouvez, par exemple, demander une image à un serveur Web Internet et obtenir en retour les données correspondantes. Vous pouvez également échanger des objets sérialisés avec un serveur d’applications via une connexion socket. Les API de Flash Player et d’AIR proposent plusieurs classes qui permettent aux applications de participer à cet échange. Elles prennent en charge la mise en réseau IP pour les protocoles tels qu’UDP, TCP, HTTP, RTMP et RTMFP. Les classes suivantes permettent d’envoyer et de recevoir des données via un réseau : Classe Loader
Charge et télécharge les fichiers.
Echange des messages XML avec un serveur XMLSocket.
Envoie et reçoit des paquets UDP. Voir « Sockets UDP (AIR) » à la page 839
Principes de base de la mise en réseau et de la communication
Dans Flash Player, l’utilisation de la classe SharedObject mène à un résultat identique. Voir « Objets partagés » à la page 728. (Vous pouvez utiliser la classe SharedObject dans les applications AIR, mais se contenter d’enregistrer les données dans un fichier standard donne lieu à moins de restrictions.) Lorsque l’application Flash Player ou AIR doit communiquer avec une autre application Flash Player ou AIR sur le même ordinateur, vous pouvez faire appel à la classe LocalConnection. Deux processus SWF ou plus hébergés sur la même page Web peuvent ainsi communiquer entre eux. Un processus SWF qui s’exécute sur une page Web peut de même communiquer avec une application AIR. Voir « Communications avec d’autres occurrences de Flash Player et d’AIR » à la page 862 Pour communiquer avec d’autres processus non-SWF sur l’ordinateur local, vous disposez de la classe NativeProcess intégrée à AIR 2. La classe NativeProcess permet à l’application AIR de démarrer et de communiquer avec d’autres applications. Voir « Communication avec les processus natifs dans AIR » à la page 869 Les classes suivantes permettent d’obtenir des informations sur l’environnement réseau de l’ordinateur sur lequel s’exécute une application AIR :
Voir « Interfaces réseau » à la page 822.
System) » à la page 826
• URLMonitor : permet de surveiller la disponibilité d’une ressource associée à une URL donnée. Voir « Surveillance HTTP » à la page 825.
Voir « Surveillance des sockets » à la page 825. Concepts importants et terminologie La liste de référence suivante contient des termes importants relatifs à la programmation de code de mise en réseau et de communication : Données externes Données stockées sous une certaine forme en dehors de l’application et chargées dans cette dernière si besoin est. Ces données peuvent être stockées dans un fichier chargé directement, dans une base de données ou sous une autre forme récupérée en appelant des scripts ou des programmes exécutés sur un serveur. Variables codées URL Le format codé URL permet de représenter plusieurs variables (paires de valeurs et de noms de variable) dans une seule chaîne de texte. Les variables individuelles sont écrites dans le format nom=valeur. Chaque variable (c’est-à-dire, chaque paire nom-valeur) est séparée par un caractère esperluette, comme suit : variable1=valeur1&variable2=valeur2. De cette façon, un nombre infini de variables peut être envoyé sous la forme d’un seul message. Type MIME Code standard utilisé pour identifier le type d’un fichier donné dans une communication Internet. Tous
HTTP Hypertext Transfer Protocol : format standard de livraison de pages Web et de différents types de contenu
Méthode de requête Lorsqu’une application (tel un navigateur Web ou une application AIR) envoie un message (appelé requête HTTP) à un serveur Web, les données envoyées peuvent être intégrées à la requête de deux façons
différentes : les méthodes de requête GET et POST. Côté serveur, le programme qui reçoit la requête doit pouvoir rechercher les données dans la portion appropriée de la requête. C’est pourquoi la méthode de requête utilisée pour envoyer des données de votre application doit correspondre à celle utilisée pour lire ces données sur le serveur. Connexions socket Connexion persistante pour la communication entre deux ordinateurs. Charger Envoyer un fichier à un autre ordinateur. Télécharger Récupérer un fichier d’un autre ordinateur.
Adobe AIR 2 et ultérieur L’objet NetworkInfo permet de vérifier les interfaces matérielles et logicielles réseau dont dispose l’application. Puisqu’il s’agit d’un objet singleton, il est inutile de le créer. Accédez à l’unique objet NetworkInfo par le biais de la propriété de classe statique networkInfo. L’objet NetworkInfo distribue également un événement networkChange en cas de modification de l’une des interfaces disponibles. Appelez la méthode findInterfaces() pour obtenir la liste des objets NetworkInterface. Chaque objet NetworkInterface de la liste décrit l’une des interfaces disponibles. L’objet NetworkInterface fournit des informations telles que l’adresse IP, l’adresse matérielle, l’unité maximale de transmission et indique si l’interface est active. L’exemple de code suivant effectue le suivi des propriétés NetworkInterface de chaque interface sur l’ordinateur client : package { import flash.display.Sprite; import flash.net.InterfaceAddress; import flash.net.NetworkInfo; import flash.net.NetworkInterface; public class NetworkInformationExample extends Sprite { public function NetworkInformationExample() { var networkInfo:NetworkInfo = NetworkInfo.networkInfo; var interfaces:Vector.<NetworkInterface> = networkInfo.findInterfaces(); if( interfaces != null ) Adobe AIR envoie un événement de changement réseau à chaque fois qu’une connexion réseau est disponible ou non disponible. L’objet NetworkInfo et l’objet NativeApplication de l’application distribuent tous deux l’événement networkChange. Pour répondre à cet événement, ajoutez un écouteur : NetworkInfo.networkInfo.addEventListener(Event.NETWORK_CHANGE, onNetworkChange);
L’événement networkChange n’indique pas un changement de l’activité réseau globale. Il se contente de signaler qu’une connexion réseau donnée a changé. AIR ne tente pas d’interpréter la signification du changement réseau. Un ordinateur connecté au réseau étant susceptible de disposer d’un nombre élevé de connexions réelles et virtuelles, perdre une connexion ne signifie pas nécessairement perdre une ressource. A l’inverse, une nouvelle connexion n’est pas non plus synonyme de disponibilité accrue des ressources. Il arrive qu’une nouvelle connexion bloque l’accès à des ressources précédemment disponibles (lors d’une connexion à un VPN, par exemple). En règle générale, l’unique façon de déterminer si une application peut se connecter à une ressource distante consiste à en faire l’essai. La structure de surveillance des services propose une technique orientée événement de réponse aux changements de connectivité réseau vers un hôte déterminé. Remarque : la structure de surveillance des services détecte si un serveur répond de manière acceptable à une requête. Le succès du contrôle n’est pas synonyme de connectivité totale. Les services Web évolutifs proposent souvent des dispositifs de mise en cache et d’équilibrage de charge destinés à réorienter le trafic vers un groupe de serveurs Web. Dans ce cas de figure, les prestataires de services n’assurent qu’un diagnostic partiel de la connectivité réseau.
Adobe AIR 1.0 et les versions ultérieures La structure de surveillance des services, distincte de la structure AIR, réside dans le fichier aircore.swc. Pour pouvoir utiliser la structure, le fichier aircore.swc doit être inclus dans le processus de compilation. Adobe® Flash® Builder inclut automatiquement cette bibliothèque. La classe ServiceMonitor met en œuvre la structure de surveillance des services réseau et propose des fonctionnalités de base aux utilitaires de surveillance des services. Par défaut, une occurrence de la classe ServiceMonitor distribue des événements relatifs à la connectivité réseau. L’objet ServiceMonitor distribue ces événements lors de la création de l’occurrence et lorsque le moteur d’exécution détecte un changement au sein du réseau. Par ailleurs, vous pouvez définir la propriété pollInterval d’une occurrence de ServiceMonitor de sorte à vérifier la connectivité à fréquence déterminée exprimée en millisecondes, sans tenir compte des événements de connectivité réseau généraux. Un objet ServiceMonitor ne vérifie pas la connectivité réseau tant que la méthode start() n’a pas été appelée. La classe URLMonitor, une sous-classe de la classe ServiceMonitor, détecte les changements de connectivité HTTP associés à une requête URLRequest déterminée. La classe SocketMonitor, également une sous-classe de la classe ServiceMonitor, détecte les changements de connectivité vers un hôte déterminé sur un port donné. Remarque : dans les versions antérieures à AIR 2, la structure de surveillance des services était publiée dans la bibliothèque servicemonitor.swc. L’utilisation de cette bibliothèque est à présent déconseillée. Utilisez plutôt la bibliothèque aircore.swc. Flash CS4 et CS5 Professional Pour utiliser ces classes dans Adobe® Flash® CS4 ou CS5 Professional : 1 Choisissez Fichier > Paramètres de publication. 2 Cliquez sur le bouton Paramètres pour ActionScript 3.0. Sélectionnez Chemin de la bibliothèque. 3 Cliquez sur le bouton Localiser le fichier SWC et accédez au dossier AIK dans le dossier d’installation de Flash
4 Dans ce dossier, recherchez le fichier /frameworks/libs/air/aircore.swc (AIR 2) ou
6 Ajoutez l’instruction d’importation suivante dans votre code ActionScript 3.0 : import air.net.*;
URLMonitor pour détecter les changements de connectivité vers le site Web d’Adobe : import air.net.URLMonitor; import flash.net.URLRequest; import flash.events.StatusEvent; var monitor:URLMonitor; monitor = new URLMonitor(new URLRequest('http://www.example.com')); monitor.addEventListener(StatusEvent.STATUS, announceStatus); monitor.start(); function announceStatus(e:StatusEvent):void { trace("Status change. Current status: " + monitor.available); }
Adobe AIR 1.0 et les versions ultérieures Les applications AIR peuvent également utiliser les connexions de socket pour assurer la connectivité de type « push ». Pour des raisons de sécurité, les pare-feu et routeurs réseau interdisent généralement les communications réseau sur les ports non autorisés. Les développeurs doivent donc tenir compte du fait que les utilisateurs ne sont pas toujours à même d’établir des connexions de socket. Le code suivant utilise une occurrence de la classe SocketMonitor pour détecter les changements de connectivité vers une connexion de socket : Le port surveillé, 6667, est un port courant pour IRC : import air.net.ServiceMonitor; import flash.events.StatusEvent; socketMonitor = new SocketMonitor('www.example.com',6667); socketMonitor.addEventListener(StatusEvent.STATUS, socketStatusChange); socketMonitor.start(); function announceStatus(e:StatusEvent):void { trace("Status change. Current status: " + socketMonitor.available); }
Adobe AIR 2.0 et les versions ultérieures La classe DNSResolver permet de consulter les enregistrements de ressource DNS. Les enregistrements de ressource DNS fournissent des informations telles que l’adresse IP d’un nom de domaine et le nom de domaine d’une adresse IP. Vous pouvez consulter les types suivants d’enregistrements de ressources DNS :
• AAAARecord : adresse IPv6 d’un hôte • MXRecord : enregistrement d’échange de courrier associé à un hôte Pour consulter un enregistrement, transmettez une chaîne de requête et l’objet de classe représentant le type d’enregistrement à la méthode lookup() de l’objet DNSResolver. La chaîne de requête à utiliser varie selon le type d’enregistrement : Classe d’enregistrement
Principes de base de la mise en réseau et de la communication
{ import import import import import
L’API de Flash Player comprend également la classe XMLSocket. La classe XMLSocket utilise un protocole propre à Flash Player, qui permet d’échanger des messages XML avec un serveur qui comprend ce protocole. La classe XMLSocket a été introduite dans ActionScript 1 et continue à être prise en charge à des fins de compatibilité ascendante. En règle générale, réservez la classe Socket aux nouvelles applications, sauf si vous vous connectez à un serveur dédié aux communications avec Flash XMLSockets. Adobe AIR intègre plusieurs autres classes réservées à la programmation réseau basée sur les sockets. Les applications AIR peuvent agir comme serveurs sockets TCP grâce à la classe ServerSocket, et peuvent se connecter à des serveurs sockets qui requièrent une sécurité SSL ou TLS grâce à la classe SecureSocket. La classe DatagramSocket permet également aux applications AIR d’envoyer et de recevoir des messages UDP (Universal Datagram Protocol).
Package flash.net « Connexion aux sockets » à la page 1114 Les API ActionScript suivantes assurent des connexions TCP :
• XMLSocket : permet à une application cliente de se connecter à un serveur XMLSocket.
IMAP et NNTP, par exemple). Ces interactions permettent alors aux applications de se connecter à des serveurs de messagerie et d’informations. Flash Player peut communiquer directement avec un serveur en utilisant directement le protocole binaire de ce serveur. Certains serveurs utilisent l’ordre d’octets « gros-boutiste », d’autres l’ordre « petit-boutiste ». La plupart des serveurs sur Internet utilisent l’ordre gros-boutiste, car il s’agit de l’ordre d’octets du réseau. L’ordre petit-boutiste s’est répandu en raison de son utilisation par l’architecture Intel® x86. Vous devez utiliser l’ordre d’octets correspondant au serveur qui envoie et reçoit les données. Toutes les opérations sont effectuées par les interfaces IDataInput et IDataOutput, et les classes qui les implémentent (ByteArray, Socket et URLStream) sont par défaut encodées au format gros-boutiste (l’octet le plus significatif en premier). Cet ordre d’octet par défaut a été sélectionné pour correspondre à Java et à l’ordre des octets réseau officiel. Pour modifier l’ordre d’octets à utiliser, vous pouvez définir la propriété endian sur Endian.BIG_ENDIAN ou Endian.LITTLE_ENDIAN. la classe Socket hérite de toutes les méthodes définies par les interfaces IDataInput et IDataOutput (qui résident dans le package flash.utils). Vous devez impérativement utiliser ces méthodes pour écrire et lire à partir du socket. Pour plus d’informations, voir :
• IDataInput (SSLv4) ou Transport Layer Security version 1 (TLSv1). Les avantages que présente un socket sécurisé sont au nombre de trois : authentification du serveur, intégrité des données et confidentialité des messages. Le moteur d’exécution authentifie un serveur par le biais de son certificat et de sa relation aux certificats délivrés par les autorités de certification racine ou intermédiaires dans le magasin d’approbation de l’utilisateur. Le moteur d’exécution se fonde sur les algorithmes de cryptographie utilisés par les implémentations de protocoles SSL et TLS pour assurer l’intégrité des données et la confidentialité des messages.
La classe CertificateStatus définit les constantes de chaîne qui représentent les résultats possibles de la validation :
• Invalid (Non valide) : diverses raisons expliquent la non-validité d’un certificat. Celui-ci pourrait avoir été modifié, altéré ou son type pourrait être incorrect.
• Trusted (Fiable) : le certificat est valide et fiable. Pour qu’un objet SecureSocket puisse se connecter à un serveur, ce dernier doit disposer d’un certificat valide et fiable.
Pour plus d’informations, voir :
• CertificateStatus • Création d’un client Telnet personnalisé à l’aide de la classe Socket
Le fichier principal TelnetSocket.mxml se charge de créer l’interface utilisateur (IU) de l’application entière. Outre l’IU, ce fichier définit deux méthodes, login() et sendCommand(), qui permettent la connexion de l’utilisateur au serveur spécifié. L’exemple suivant répertorie le code ActionScript du fichier d’application principal : import com.example.programmingas3.socket.Telnet; private var telnetClient:Telnet; private function connect():void { telnetClient = new Telnet(serverName.text, int(portNumber.text), output); console.title = "Connecting to " + serverName.text + ":" + portNumber.text; console.enabled = true; } private function sendCommand():void La classe Telnet se charge d’établir la connexion au serveur distant Telnet et d’envoyer et de recevoir les données. La classe Telnet déclare les variables privées suivantes : private private private private private
La quatrième variable, ta, est une référence à l’occurrence du composant TextArea sur la scène. Ce composant sert à afficher les réponses provenant du serveur Telnet distant ou les éventuels messages d’erreur. La dernière variable, state, est une valeur numérique utilisée pour déterminer les options prises en charge par le client Telnet. Comme vous l’avez vu précédemment, la fonction constructeur de la classe Telnet est appelée par la méthode connect() dans le fichier d’application principal. Le constructeur Telnet prend trois paramètres : server, port et output. Les paramètres server et port spécifient le nom et le numéro de port du serveur Telnet. Le dernier paramètre, output, est une référence à une occurrence du composant TextArea sur la scène où s’affichent les résultats du serveur à l’intention de l’utilisateur. public function Telnet(server:String, port:int, output:TextArea) { serverURL = server; portNumber = port; ta = output; socket = new Socket(); socket.addEventListener(Event.CONNECT, connectHandler); socket.addEventListener(Event.CLOSE, closeHandler); socket.addEventListener(ErrorEvent.ERROR, errorHandler); socket.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler); socket.addEventListener(ProgressEvent.SOCKET_DATA, dataHandler); Security.loadPolicyFile("http://" + serverURL + "/crossdomain.xml"); try { msg("Trying to connect to " + serverURL + ":" + portNumber + "\n"); socket.connect(serverURL, portNumber); Pour écrire des données sur une connexion socket, vous appelez l’une des méthodes d’écriture de la classe Socket. Parmi ces méthodes d’écriture figurent writeBoolean(), writeByte(), writeBytes(), writeDouble(), etc. Purgez ensuite les données dans le tampon de sortie par le biais de la méthode flush(). Sur le serveur Telnet, les données sont écrites sur la connexion Socket à l’aide de la méthode writeBytes(), qui prend comme paramètre le tableau d’octets et l’envoie au tampon de sortie. La méthode writeBytesToSocket() se présente comme suit : public function writeBytesToSocket(ba:ByteArray):void { socket.writeBytes(ba); socket.flush(); }
Affichage des messages provenant du serveur socket Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Dès qu’un message est reçu du serveur socket ou qu’un événement se produit, la méthode personnalisée msg() est appelée. Cette méthode ajoute une chaîne au composant TextArea sur la scène et appelle une méthode setScroll() personnalisée, qui provoque le défilement vers le bas du composant TextArea. La méthode msg() se présente comme suit : private function msg(value:String):void { ta.text += value; setScroll(); }
Défilement du contenu d’un composant TextArea Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La méthode setScroll() contient une seule ligne de code ActionScript qui permet de faire défiler verticalement le contenu du composant TextArea de manière que l’utilisateur puisse voir la dernière ligne de texte renvoyé. L’extrait de code suivant illustre la méthode setScroll() : public function setScroll():void { ta.verticalScrollPosition = ta.maxVerticalScrollPosition; }
La classe XMLSocket ne peut pas automatiquement tunneler à travers les pare-feux car, contrairement au protocole RTMP (Real-Time Messaging Protocol), le XMLSocket n’a pas de capacité de tunneling HTTP. Si vous devez utiliser le tunneling HTTP, envisagez l’emploi de Flash Remoting ou Flash Media Server (qui prend en charge RTMP). Les restrictions suivantes indiquent comment et où le contenu situé dans Flash Player ou une application AIR hors du sandbox de sécurité de l’application peut utiliser un objet XMLSocket pour se connecter au serveur :
Remarque : la configuration d’un serveur en vue de la communication avec un objet XMLSocket peut être difficile à réaliser. Si votre application ne requiert pas d’interactivité en temps réel, utilisez la classe URLLoader, plutôt que la classe XMLSocket. Vous pouvez utiliser les méthodes XMLSocket.connect() et XMLSocket.send() de la classe XMLSocket pour transférer un objet XML vers et à partir d’un serveur sur une connexion socket. La méthode XMLSocket.connect() établit une connexion socket avec le port d’un serveur Web. La méthode XMLSocket.send() transmet un objet XML au serveur spécifié dans la connexion socket. Lorsque vous appelez la méthode XMLSocket.connect(), l’application ouvre une connexion TCP/IP avec le serveur et garde cette connexion ouverte jusqu’à ce que l’un des événements suivants se produise :
• Il n’existe plus aucune référence à l’objet XMLSocket. • Flash Player se ferme. • La connexion est interrompue (le modem est déconnecté, par exemple).
Pour créer une connexion socket, vous devez créer une application côté serveur qui attend la demande de connexion socket et envoie une réponse à l’application Flash Player ou AIR. Ce type d’application côté serveur peut être programmé en AIR ou dans tout autre langage de programmation tel que Java, Python ou Perl. Pour utiliser la classe XMLSocket, l’ordinateur serveur doit exécuter un démon capable de lire le protocole simple utilisé par la classe XMLSocket :
• Chaque message XML est un document XML complet, terminé par un octet nul (0). • Un nombre illimité de messages XML peut être envoyé et reçu via une connexion XMLSocket. Création d’un serveur socket XML Java et connexion à ce serveur Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le code suivant illustre un simple serveur XMLSocket écrit en langage Java qui accepte les connexions entrantes et affichent les messages reçus dans la fenêtre d’invite de commande. Par défaut, un nouveau serveur est créé sur le port 8080 de votre machine locale, mais vous pouvez spécifier un numéro de port différent en lançant le serveur à partir de la ligne de commande. Créez un document texte et ajoutez-y le code suivant : import java.io.*; import java.net.*; class SimpleServer { private static SimpleServer server; ServerSocket socket; Socket incoming; SimpleServer.class peut se situer à tout emplacement sur l’ordinateur local ou le réseau ; il n’est pas nécessaire de le placer dans le répertoire racine du serveur Web. si vous ne pouvez pas lancer le serveur parce que des fichiers ne se trouvent pas dans le chemin de classe Java, essayez de le faire avec java -classpath. SimpleServer. Pour établir une connexion au serveur XMLSocket à partir de l’application, vous devez créer une nouvelle occurrence de la classe XMLSocket et appeler la méthode XMLSocket.connect() tout en transférant le nom d’hôte et le numéro de port, comme suit : var xmlsock:XMLSocket = new XMLSocket(); xmlsock.connect("127.0.0.1", 8080);
La méthode XMLSocket.send() ne renvoie pas de valeur indiquant si les données ont bien été transmises. Si une erreur se produit pendant la tentative d’envoi des données, une erreur IOError est renvoyée. chaque message que vous envoyez au serveur socket doit se terminer par un caractère de changement de ligne (\n). Pour plus d’informations, voir XMLSocket.
Adobe AIR 2 et ultérieur La classe ServerSocket permet d’autoriser d’autres processus à se connecter à l’application par le biais d’un socket TCP (Transport Control Protocol). Le processus de connexion peut s’exécuter sur l’ordinateur local ou un autre ordinateur connecté au réseau. Lorsqu’un objet ServerSocket reçoit une demande de connexion, il distribue un événement connect. L’objet ServerSocketConnectEvent distribué avec l’événement contient un objet Socket. Cet objet permet de communiquer ultérieurement avec l’autre processus. Pour écouter les connexions socket entrantes : 1 Créez un objet ServerSocket et liez-le à un port local. 2 Ajoutez des écouteurs d’événements associés à l’événement connect. 3 Appelez la méthode listen(). 4 Répondez à l’événement connect, qui fournit un objet Socket pour chaque connexion entrante.
L’exemple de code suivant illustre la création d’une application de serveur socket. L’exemple écoute les connexions entrantes sur le port 8087. Lorsqu’une connexion est reçue, l’exemple envoie un message (la chaîne « Connected ») au socket client. Le serveur renvoie désormais tout message reçu au client.
à l’application de destination plus rapidement que les messages TCP. Les communications de type sockets UDP s’avèrent utiles lorsque vous devez envoyer des informations en temps réel telles qu’une actualisation des positions dans le cadre d’un jeu ou des paquets son dans une application de conversation vocale. Dans les applications de ce type, un certain pourcentage de perte de données est acceptable et une faible latence de transmission prime sur la livraison garantie. Dans quasiment tous les autres cas de figure, il est préférable d’utiliser les sockets TCP.
3 Liez le socket à une adresse IP locale et à un port par le biais de la méthode bind(). 4 Envoyez des messages en appelant la méthode send() et en transmettant l’adresse IP et le port de l’ordinateur cible. 5 Répondez à l’événement data pour recevoir des messages. L’objet DatagramSocketDataEvent distribué pour cet
L’exemple de code suivant illustre l’envoi et la réception de messages UDP par une application. L’exemple envoie un message simple contenant la chaîne « Hello. » à l’ordinateur cible. Il effectue également le suivi du contenu de tout message reçu. package { import flash.display.Sprite; import flash.events.DatagramSocketDataEvent; import flash.events.Event; import flash.net.DatagramSocket; import flash.utils.ByteArray; public class DatagramSocketExample extends Sprite { private var datagramSocket:DatagramSocket; //The IP and port for this computer private var localIP:String = "192.168.0.1"; private var localPort:int = 55555; • Il ne se produit pas de négociation entre l’expéditeur et la cible. Les messages sont ignorés sans générer d’erreur si la cible n’existe pas ou qu’aucun écouteur actif n’est défini sur le port indiqué.
Pour plus d’informations, voir :
• DatagramSocketDataEvent • Les chiffres hexadécimaux sont en bas de casse seulement. • Les adresses IPv6 sont entourées de crochets ([]). • Chaque quatuor d’adresses est représenté par 0 à 4 chiffres hexadécimaux, sans zéros non significatifs. • Un quatuor d’adresses de zéros est représenté par un seul zéro (et pas un caractère de deux-points redoublé), sauf dans les cas suivants. Les valeurs IPv6 que renvoie Flash Player sont soumises aux exceptions suivantes :
• L’adresse de bouclage (loopback) ou localhost IPv6 est représentée par [::1]. • Les adresses mappées en IPv4 (converties en IPv6) sont représentées par [::ffff:a.b.c.d], où a.b.c.d constitue une valeur décimale à points (dotted-decimal) IPv4 classique.
(dotted-decimal) IPv4 classique.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Un grand nombre d’API qui chargent des données externes font appel à la classe URLRequest pour définir les propriétés de la requête réseau requise.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous pouvez définir les propriétés suivantes d’un objet URLRequest dans tout sandbox de sécurité :
Définition des paramètres par défaut des objets URLRequest (AIR uniquement) Adobe AIR 1.0 et les versions ultérieures La classe URLRequestDefaults permet de définir les paramètres par défaut propres à une application des objets URLRequest. Par exemple, le code suivant définit les valeurs par défaut des propriétés manageCookies et useCache. Tous les nouveaux objets URLRequest utiliseront les valeurs spécifiées de ces propriétés au lieu des valeurs par défaut standard :
"www.example.com:80". Notez que "example.com", "www.example.com" et "sales.example.com" sont considérés comme hôtes uniques. Ces informations d’identification ne sont utilisées que lorsque le serveur les demande. Si l’utilisateur s’est déjà authentifié (à l’aide de la boîte de dialogue d’authentification, par exemple), appeler la méthode setLoginCredentialsForHost() ne modifie pas l’utilisateur authentifié. Le code suivant permet de définir le nom d’utilisateur et le mot de passe par défaut à utiliser pour les requêtes envoyées à www.example.com : URLRequestDefaults.setLoginCredentialsForHost("www.example.com", "Ada", "love1816$X");
Pour plus d’informations, voir la classe URLRequestDefaults dans le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash.
Les modèles d’URI standard, tel le modèle ci-dessous, peuvent être utilisés dans les requêtes effectuées à partir de tout sandbox de sécurité : http: et https: A utiliser pour les URL Internet standard (comme elles sont utilisées dans un navigateur Web). file: Utilisez file: pour spécifier l’URL d’un fichier qui réside dans le système de fichiers local. Exemple : file:///c:/AIR Test/test.txt
Le modèle app: permet de spécifier un chemin relatif au répertoire racine de l’application installée. Par exemple, le chemin suivant pointe vers un sous-répertoire de ressources du répertoire de l’application installée : app:/resources
L’URL (et la propriété url) d’un objet File créé avec File.applicationDirectory fait appel au modèle d’URI app, comme dans l’exemple suivant :
Néanmoins, vous ne pouvez utiliser ces modèles d’URI spécifiques à AIR (app: et app-storage:) que dans le contenu du sandbox de sécurité de l’application. Pour plus d’informations, voir « Sécurité AIR » à la page 1122.
Les méthodes permettant d’ajouter des paramètres à un objet URLVariables sont au nombre de trois :
• A l’aide de la méthode URLVariables.decode() • Sous forme de propriétés dynamiques de l’objet URLVariables en tant que tel L’exemple suivant illustre les trois méthodes et indique comment affecter les variables à un objet URLRequest : var urlVar:URLVariables = new URLVariables( "one=1&two=2" ); urlVar.decode("amp=" + encodeURIComponent( "&" ) ); urlVar.three = 3; urlVar.amp2 = "&&"; trace(urlVar.toString()); //amp=%26&2=%26%26&one=1&two=2&three=3 var urlRequest:URLRequest = new URLRequest( "http://www.example.com/test.cfm" ); urlRequest.data = urlVar;
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe URLLoader permet d’envoyer une requête à un serveur et d’accéder aux informations renvoyées. Vous disposez également de la classe URLLoader pour accéder aux fichiers du système de fichiers local dans les contextes où l’accès aux fichiers locaux est autorisé (le sandbox local avec système de fichiers de Flash Player et le sandbox d’application AIR, par exemple). La classe URLLoader télécharge des données à partir d’une URL sous forme de texte, de données binaires ou de variables codées au format URL. La classe URLLoader distribue des événements tels que complete, httpStatus, ioError, open, progress et securityError. Le modèle de gestion des événements d’ActionScript 3.0 est sensiblement différent du modèle d’ActionScript 2.0, qui utilisait les gestionnaires d’événement LoadVars.onData, LoadVars.onHTTPStatus et LoadVars.onLoad. Pour plus d’informations sur la gestion des événements en ActionScript 3.0, voir « Gestion des événements » à la page 129. Les données téléchargées ne sont pas disponibles tant que le téléchargement n’est pas terminé. Pour surveiller la progression du téléchargement (nombre d’octets chargés et nombre total d’octets), écoutez la distribution de l’événement progress. Toutefois, si le chargement d’un fichier est rapide, l’événement progress risque de ne pas être distribué. Une fois que le téléchargement d’un fichier est terminé, l’événement complete est distribué. En définissant la propriété dataFormat de la classe URLLoader, vous pouvez recevoir les données sous forme de texte, de données binaires brutes ou d’objet URLVariables. La méthode URLLoader.load() (et éventuellement le constructeur de la classe URLLoader) gère un seul paramètre, request, qui correspond à un objet URLRequest. Un objet URLRequest contient toutes les informations d’une requête HTTP unique, telles que l’URL cible, la méthode de requête (GET ou POST), d’autres informations d’en-tête et le type MIME. Pour charger un paquet XML dans un script côté serveur, par exemple, vous pouvez utiliser le code ci-après : var secondsUTC:Number = new Date().time; var dataXML:XML = <clock> <time>{secondsUTC}</time> Dernière mise à jour le 27/4/2013
La classe URLStream permet d’accéder aux données en cours de téléchargement au fur et à mesure de leur arrivée. Elle permet également de fermer un flux continu avant la fin du téléchargement. Les données téléchargées sont disponibles au format binaire brut. Lorsque vous lisez les données issues d’un objet URLStream, faites appel à la propriété bytesAvailable pour déterminer si les données disponibles sont suffisantes avant de les lire. Une exception EOFError est renvoyée si vous essayez de lire des données qui ne sont pas disponibles. Evénement httpResponseStatus (AIR) Dans Adobe AIR, la classe URLStream distribue un événement httpResponseStatus en plus de l’événement httpStatus. L’événement httpResponseStatus est envoyé avant toute donnée de réponse. L’événement httpResponseStatus (représenté par la classe HTTPStatusEvent) inclut une propriété responseURL, qui correspond à l’URL que la réponse a renvoyée, et une propriété responseHeaders, qui est un tableau d’objets URLRequestHeader représentant les en-têtes de réponse que la réponse a renvoyés.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lorsque vous programmez des applications dynamiques, il peut s’avérer utile de charger des données issues de fichiers externes ou de scripts côté serveur. Vous pouvez ainsi programmer des applications dynamiques sans avoir à les modifier ou les recompiler. Par exemple, si vous créez une application « conseil du jour », vous pouvez écrire un script côté serveur qui récupère un conseil au hasard dans une base de données et l’enregistre dans un fichier texte une fois par jour. Votre application peut ensuite charger le contenu du fichier texte statique au lieu d’envoyer une requête à la base de données à chaque fois. L’extrait de code suivant crée un objet URLRequest et URLLoader, qui charge le contenu d’un fichier texte externe nommé params.txt : var request:URLRequest = new URLRequest("params.txt"); var loader:URLLoader = new URLLoader(); loader.load(request);
à l’aide de la constante statique URLRequestMethod.POST, comme l’illustre le code suivant : var request:URLRequest = new URLRequest("sendfeedback.cfm"); request.method = URLRequestMethod.POST;
URLLoaderDataFormat. Les trois valeurs possibles de la propriété URLLoader.dataFormat sont les suivantes :
URLVariables en attribuant à la propriété URLLoader.dataFormat la valeur URLLoaderDataFormat.VARIABLES.
XML, que vous pouvez analyser avec les méthodes et propriétés XML.
Outre le chargement de fichiers de données externes, la classe URLVariables permet d’envoyer des variables à un script côté serveur et de traiter la réponse du serveur. Cela s’avère utile, par exemple, si vous programmez un jeu et souhaitez envoyer le score de l’utilisateur à un serveur afin de vérifier s’il faut l’ajouter à la liste des scores les plus élevés ; ou encore envoyer les informations de connexion de l’utilisateur au serveur pour validation. Un script côté serveur peut traiter le nom d’utilisateur et le mot de passe, les comparer à une base de données et confirmer en retour la validité des informations fournies par l’utilisateur. L’extrait de code ci-après crée un objet URLVariables nommé variables, qui génère une nouvelle variable appelée name. Ensuite, un objet URLRequest est créé pour spécifier l’URL du script côté serveur à laquelle doivent être envoyées les variables. Vous pouvez alors définir la propriété method de l’objet URLRequest pour envoyer les variables sous forme de requête HTTP POST . Pour ajouter l’objet URLVariables à la requête URL, définissez la propriété data de l’objet URLRequest sur l’objet URLVariables créé plus tôt. Enfin, l’occurrence de URLLoader est créée et la méthode URLLoader.load() appelée ; cette dernière lance la requête.
Dans les applications AIR HTML, vous disposez des classes URLRequest et URLLoader ou de la classe XMLHttpRequest de JavaScript. Le cas échéant, vous pouvez également créer une bibliothèque SWF qui expose les composants du service Web de la structure Flex au code JavaScript.
Dans les applications AIR, un fichier de régulation interdomaines n’est pas obligatoire si l’appel au service Web provient du sandbox de sécurité d’application. Un contenu d’application AIR n’est jamais transmis par un serveur qui réside dans un domaine distant. Il ne peut donc pas participer aux types d’attaques bloquées par les régulations interdomaines. Dans les applications AIR HTML, un contenu situé dans le sandbox de sécurité d’application peut générer des requêtes XMLHttpRequests interdomaines. Vous pouvez autoriser un contenu situé dans d’autres sandbox de sécurité à générer des requêtes XMLHttpRequests interdomaines, sous réserve que le contenu soit chargé dans un iframe.
« Contrôles de site Web (fichiers de régulation) » à la page 1095 Adobe BlazeDS Adobe LiveCycle ES2 Pour accéder à un service Web de type REST en ActionScript, vous disposez des classes URLRequest, URLVariables et URLLoader. Si le code JavaScript est intégré à une application AIR, vous pouvez également faire appel à une requête XMLHttpRequest. La programmation d’un appel au service Web de type REST en ActionScript implique généralement la procédure suivante : 1 Créez un objet URLRequest. 2 Associez l’URL du service et le verbe de la méthode HTTP à l’objet de la requête. 3 Créez un objet URLVariables. 4 Définissez les paramètres de l’appel au service sous forme de propriétés dynamiques de l’objet variables. 5 Affectez l’objet variables à la propriété data de l’objet de la requête. 6 Envoyez l’appel au service à l’aide d’un objet URLLoader.
L’exemple suivant fait appel aux méthodes DOM pour créer un message XML-RPC et à une requête XMLHttpRequest pour effectuer la transaction avec le service Web : <html> <head> <title>XML-RPC web service request</title> SOAP le plus simple, vous gagnerez probablement un temps considérable en phase de développement si vous utilisez une bibliothèque SOAP existante. La structure Flex intègre des bibliothèques permettant d’accéder aux services Web SOAP. Dans Flash Builder, la bibliothèque, rpc.swc, est automatiquement intégrée aux projets Flex, puisqu’elle fait partie de la structure Flex. Dans Flash Professional, vous pouvez ajouter les fichiers Flex framework.swc et rpc.swc au chemin de la bibliothèque d’un projet, puis accéder aux classes Flex à l’aide d’ActionScript.
Utilisation du composant de service Web Flex dans Flash Professional Christophe Coenraets : Real-time Trader Desktop for Android (disponible en anglais uniquement) Vous disposez de la fonction navigateToURL() pour ouvrir une URL dans un navigateur Web ou une autre application. Si le contenu s’exécute dans AIR, la fonction navigateToURL() ouvre la page dans le navigateur Web par défaut du système. Pour l’objet URLRequest que vous transmettez comme paramètre request de cette fonction, seule la propriété url est utilisée. Le premier paramètre de la fonction navigateToURL(), le paramètre navigate, est un objet URLRequest (voir « Utilisation de la classe URLRequest » à la page 843). Le deuxième paramètre est un paramètre window facultatif, dans lequel vous pouvez spécifier le nom de la fenêtre. Le code suivant ouvre par exemple la page Web www.adobe.com : var url:String = "http://www.adobe.com"; var urlReq:URLRequest = new URLRequest(url); navigateToURL(urlReq);
Si vous utilisez la fonction navigateToURL(), les modèles d’URI sont autorisés en fonction du sandbox de sécurité du code qui appelle la fonction navigateToURL(). Certaines API permettent de lancer le contenu dans un navigateur Web. Pour des raisons de sécurité, certains modèles d’URI sont interdits lors de l’utilisation de ces API dans AIR. La liste des modèles non autorisés dépend du sandbox de sécurité du code utilisant l’API. (Pour plus d’informations sur les sandbox de sécurité, voir le chapitre « Sécurité AIR » à la page 1122.) Sandbox de l’application (AIR uniquement) Vous pouvez utiliser n’importe quel modèle d’URI dans l’URL activée par le contenu s’exécutant dans le sandbox de l’application AIR. Une application doit être enregistrée pour gérer le modèle d’URI. Dans le cas contraire, la demande n’aboutit pas. Les modèles suivants sont pris en charge sur de nombreux périphériques et ordinateurs :
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe LocalConnection permet de développer des fichiers SWF qui peuvent échanger des instructions avec d’autres fichiers SWF sans utiliser la méthode fscommand() ou JavaScript. Les objets LocalConnection peuvent uniquement communiquer entre des fichiers SWF exécutés sur le même ordinateur client, mais ils peuvent concerner différentes applications. Par exemple, un fichier SWF exécuté dans un navigateur et un fichier SWF de projection peuvent partager des informations, le fichier de projection se chargeant de maintenir les informations locales et le fichier SWF du navigateur se connectant à distance. (un fichier de projection est un fichier SWF enregistré dans un format tel qu’il peut s’exécuter de manière autonome ; il n’est donc pas nécessaire de disposer de Flash Player pour le lire, car il est incorporé dans le fichier exécutable). Les objets LocalConnection peuvent être utilisés pour communiquer entre des SWF utilisant différentes versions d’ActionScript :
LocalConnection créés dans ActionScript 3.0.
LocalConnection créés dans ActionScript 3.0. Flash Player gère automatiquement les communications entre les objets LocalConnection de versions différentes. La façon la plus simple d’utiliser un objet LocalConnection consiste à autoriser la communication uniquement entre des objets LocalConnection se trouvant dans le même domaine ou dans la même application AIR. Vous évitez ainsi les problèmes de sécurité. Toutefois, si vous devez autoriser les communications entre les domaines, vous disposez de diverses méthodes pour mettre en œuvre des mesures de sécurité. Pour plus d’informations, voir l’analyse du paramètre connectionName de la méthode send(), ainsi que les entrées allowDomain() et domain dans le code associé à la classe LocalConnection du manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash. Il est possible d’utiliser des objets LocalConnection pour envoyer et recevoir des données au sein d’un fichier SWF unique. Toutefois, Adobe ne recommande pas cette pratique. Faites de préférence appel aux objets partagés.
• Définir la propriété LocalConnection.client sur un objet qui implémente ces méthodes • Créer une classe dynamique qui étend la classe LocalConnection et y joindre dynamiquement des méthodes La première manière d’ajouter des méthodes de rappel est d’étendre la classe LocalConnection. Vous pouvez définir les méthodes au sein de la classe personnalisée, plutôt que de les ajouter dynamiquement à l’occurrence de LocalConnection. Ceci est illustré par le code suivant :. package { import flash.net.LocalConnection; public class CustomLocalConnection extends LocalConnection { public function CustomLocalConnection(connectionName:String) { try Pour créer la classe CustomClient, vous pouvez utiliser le code suivant :
à des fins de compatibilité ascendante. Elle sera peut-être modifiée dans les versions futures des moteurs d’exécution.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous pouvez utiliser la classe LocalConnection pour communiquer d’une part entre différentes applications AIR et, d’autre part, entre différentes applications Adobe® Flash® Player (SWF) qui s’exécutent dans un navigateur. Vous disposez également de la classe LocalConnection pour communiquer entre une application AIR et une application SWF qui s’exécute dans un navigateur. Par exemple, vous pouvez utiliser plusieurs occurrences de Flash Player sur une même page Web ou vous servir d’une occurrence de Flash Player pour récupérer des données dans une occurrence de Flash Player affichée dans une fenêtre distincte. Le code ci-dessous définit un objet LocalConnection qui joue le rôle d’un serveur et qui accepte des appels LocalConnection provenant d’autres applications :
Dès qu’une occurrence de Flash Player se connecte à ce fichier SWF et essaie d’appeler l’une des méthodes de la connexion local, la requête est envoyée à la classe spécifiée par la propriété client, à savoir la classe CustomClient1 : package { import flash.events.*; import flash.system.fscommand; import flash.utils.Timer; public class CustomClient1 extends Object { public function doMessage(value:String = ""):void { trace(value); LocalConnection.send() avec le nom de la connexion et le nom de la méthode à exécuter. Par exemple, pour envoyer la méthode doQuit à l’objet LocalConnection créé précédemment, utilisez le code suivant : sendingConnection.send("conn1", "doQuit");
Pour autoriser uniquement les communications issues de domaines précis, appelez la méthode allowDomain() ou allowInsecureDomain() de la classe LocalConnection et transmettez la liste des domaines autorisés à accéder à cet objet LocalConnection. Dans les versions antérieures d’ActionScript, LocalConnection.allowDomain() et LocalConnection.allowInsecureDomain() étaient des méthodes de rappel que les développeurs devaient
LocalConnection.allowDomain() et LocalConnection.allowInsecureDomain() sont deux méthodes intégrées,
Security.allowInsecureDomain(), en transmettant un ou plusieurs noms de domaines à autoriser. Dans Flash Player 8, des restrictions de sécurité relatives aux fichiers SWF locaux ont été introduites. Un fichier SWF autorisé à accéder à Internet n’a pas accès au système de fichiers local. Si vous spécifiez localhost, tout fichier SWF local peut accéder à ce fichier SWF. Si la méthode LocalConnection.send() tente de communiquer avec un fichier SWF à partir d’un sandbox de sécurité auquel le code d’appel n’a pas accès, un événement securityError (SecurityErrorEvent.SECURITY_ERROR) est distribué. Pour contourner cette erreur, vous pouvez spécifier le domaine de l’appelant dans la méthode LocalConnection.allowDomain() du destinataire.
Si la méthode LocalConnection.send() essaie de communiquer avec une application à partir d’un sandbox de sécurité auquel le code d’appel n’a pas accès, un événement securityError (SecurityErrorEvent.SECURITY_ERROR) est distribué. Pour contourner cette erreur, vous pouvez spécifier le domaine de l’appelant dans la méthode LocalConnection.allowDomain() du destinataire. Si vous mettez en œuvre la communication uniquement entre contenus du même domaine, vous pouvez spécifier un paramètre connectionName qui ne commence pas par un caractère de soulignement (_) et ne spécifie pas un nom de domaine (par exemple myDomain:connectionName). Utilisez la même chaîne dans la commande LocalConnection.connect(connectionName). Si vous mettez en œuvre la communication entre contenus de domaines différents, spécifiez un paramètre connectionName qui commence par un caractère de soulignement. L’ajout d’un caractère de soulignement améliore la portabilité entre domaines du contenu qui possède l’objet LocalConnection de réception. Les deux cas de figure possibles sont les suivants :
_connectionName), le moteur d’exécution ne lui ajoute pas de préfixe. Les objets LocalConnection de réception et
LocalConnection.allowDomain() pour spécifier que les connexions seront acceptées à partir de tous les
Il existe un inconvénient à utiliser des noms avec caractère de soulignement dans connectionName : c’est le risque de collision. Deux applications peuvent tenter de se connecter à l’aide du même connectionName. Il en existe un deuxième lié à la sécurité. Les noms de connexion qui utilisent la syntaxe du caractère de soulignement n’identifient pas le domaine de l’application à l’écoute. C’est pour ces raisons qu’il est préférable de recourir à des noms dotés de qualificatifs de domaines. Adobe AIR Pour communiquer avec le contenu qui s’exécute dans le sandbox de sécurité de l’application AIR (contenu installé avec l’application AIR), vous devez insérer avant le nom de connexion un superdomaine qui identifie l’application AIR. La chaîne du superdomaine commence par app#, suivi de l’identifiant d’application, suivi d’un point (.), suivi de l’identifiant d’éditeur (s’il est défini). Ainsi, le superdomaine adapté au paramètre connectionName si l’identifiant d’application est com.example.air.MyApp et qu’aucun identifiant d’éditeur n’est stipulé, correspond à : « app#com.example.air.MyApp ». Par conséquent, si le nom de la connexion de base est « appConnection », la chaîne entière à utiliser dans le paramètre connectionName correspond à : « app#com.example.air.MyApp:appConnection ». Si l’application stipule l’identifiant d’éditeur, ce dernier doit être inclus dans la chaîne du superdomaine, comme suit : « app#com.example.air.MyApp.B146A943FBD637B68C334022D304CEA226D129B4.1 ».
• C’est un fichier EXE sous Windows. • C’est un package RPM ou DEB sous Linux. Ces applications portent le nom d’applications à profil de bureau étendu. Pour créer un fichier de programme d’installation natif, vous spécifiez l’option -target native lorsque vous appelez la commande -package à l’aide d’ADT.
Remarque : les applications dotées d’un profil de bureau étendu peuvent également lancer des fichiers et des applications par le biais de la méthode File.openWithDefaultApplication(). L’utilisation de cette méthode ne permet toutefois pas à l’application AIR d’accéder aux flux standard. Pour plus d’informations, voir « Ouverture de fichiers dans l’application système définie par défaut » à la page 706 Le code suivant illustre le lancement d’une application test.exe dans le répertoire d’application. L’application transmet l’argument "hello" sous forme d’argument de ligne de commande et ajoute un écouteur d’événements au flux de sortie standard du processus :
Communication avec les processus natifs dans AIR
{ var stdOut:ByteArray = process.standardOutput; var data:String = stdOut.readUTFBytes(process.standardOutput.bytesAvailable); trace("Got: ", data); • Enregistrez les arguments de ligne de commande à transmettre au processus lors du lancement (facultatif). • Définissez le répertoire de travail du processus (facultatif). Pour démarrer le processus natif, transmettez l’objet NativeProcessInfo en tant que paramètre de la méthode start() d’un objet NativeProcess. Le code suivant illustre par exemple le lancement d’une application test.exe dans le répertoire d’application. L’application transmet l’argument "hello" et définit le répertoire documents de l’utilisateur en tant que répertoire de travail : var nativeProcessStartupInfo:NativeProcessStartupInfo = new NativeProcessStartupInfo(); var file:File = File.applicationDirectory.resolvePath("test.exe"); nativeProcessStartupInfo.executable = file; var processArgs:Vector.<String> = new Vector.<String>(); processArgs[0] = "hello"; nativeProcessStartupInfo.arguments = processArgs; nativeProcessStartupInfo.workingDirectory = File.documentsDirectory; process = new NativeProcess(); process.start(nativeProcessStartupInfo);
Si vous souhaitez qu’un fichier puisse être exécuté dans l’application installée, assurez-vous qu’il peut être exécuté sur le système de fichiers lors de la mise en package de l’application. (Sous Mac et Linux, vous disposez de chmod pour définir l’indicateur executable, le cas échéant.)
Lorsqu’une application AIR démarre un processus natif, elle peut communiquer avec les flux d’entrée, de sortie et d’erreur standard de ce dernier. Vous lisez et écrivez les données dans les flux à l’aide des propriétés suivantes de l’objet NativeProcess :
NativeProcess distribue des événements standardInputProgress. S’il se produit une erreur lors de l’écriture dans le flux d’entrée standard, l’objet NativeProcess distribue un événement ioErrorStandardInput.
{ process.closeInput(); S’il se produit une erreur lors de l’écriture du flux de sortie standard, l’objet NativeProcess distribue un événement standardOutputError. Lorsque le processus ferme le flux de sortie, l’objet NativeProcess distribue un événement standardOutputClose. Veillez à lire les données issues du flux d’entrée standard au fur et à mesure de leur génération. En d’autres termes, associez un écouteur à l’événement standardOutputData. Dans l’écouteur d’événements standardOutputData, lisez les données issues de la propriété standardOutput de l’objet NativeProcess. N’attendez pas l’événement standardOutputClose ou exit pour lire l’ensemble des données. Si vous ne lisez pas les données au fur et à mesure que le processus natif les génère, la mémoire tampon risque d’être saturée ou les données de se perdre. Une mémoire tampon saturée risque d’entraîner le blocage du processus natif lorsqu’il essaie d’écrire d’autres données. Toutefois, si vous n’associez pas d’écouteur à l’événement standardOutputData, la mémoire tampon ne se remplit pas et le processus ne se bloque pas. Il vous sera dans ce cas impossible d’accéder aux données.
S’il se produit une erreur lors de l’écriture du flux d’erreur standard, l’objet NativeProcess distribue un événement standardErrorIoError.
Veillez à lire les données issues du flux d’erreur standard au fur et à mesure de leur génération. En d’autres termes, associez un écouteur à l’événement standardErrorData. Dans l’écouteur d’événements standardErrorData, lisez les données extraites de la propriété standardError de l’objet NativeProcess. N’attendez pas l’événement standardErrorClose ou exit pour lire l’ensemble des données. Si vous ne lisez pas les données au fur et à mesure que le processus natif les génère, la mémoire tampon risque d’être saturée ou les données de se perdre. Une mémoire tampon saturée risque d’entraîner le blocage du processus natif lorsqu’il essaie d’écrire d’autres données. Toutefois, si vous n’associez pas d’écouteur à l’événement standardErrorData, la mémoire tampon ne se remplit pas et le processus ne se bloque pas. Il vous sera dans ce cas impossible d’accéder aux données. var nativeProcessStartupInfo:NativeProcessStartupInfo = new NativeProcessStartupInfo(); var file:File = File.applicationDirectory.resolvePath("test.exe"); nativeProcessStartupInfo.executable = file; process = new NativeProcess(); process.addEventListener(ProgressEvent.STANDARD_ERROR_DATA, errorDataHandler); process.start(nativeProcessStartupInfo); var errorBytes:ByteArray = new ByteArray(); function errorDataHandler(event:ProgressEvent):void { bytes.writeBytes(process.standardError.readBytes(process.standardError.bytesAvailable); }
Adobe AIR 2 et ultérieur L’API de processus natif peut exécuter tout fichier exécutable sur le système de l’utilisateur. Soyez extrêmement attentif lors de la création et de l’exécution de commandes. Si toute partie d’une commande à exécuter est issue d’une source externe, vérifiez méticuleusement son intégrité avant de l’exécuter. L’application AIR doit de même valider toute donnée transmise à un processus en cours d’exécution.
Sous Windows, AIR ne vous autorise pas à exécuter directement les fichiers .bat. L’interpréteur de commande (l’application cmd.exe) exécute les fichiers .bat Windows. Lorsque vous appelez un fichier .bat, cette application peut interpréter les arguments transmis à la commande en tant applications supplémentaires à lancer. L’insertion malveillante de caractères supplémentaires dans la chaîne d’arguments risque de mener cmd.exe à exécuter une application nuisible ou non sécurisée. Ainsi, sans validation correcte des données, l’application AIR risque d’appeler myBat.bat myArguments c:/evil.exe. Outre le fichier batch, l’interpréteur de commandes lancerait l’application evil.exe.
Vous pouvez utiliser l’API externe pour interagir avec une application conteneur et transmettre les données entre ActionScript et JavaScript dans une page HTML. Exemples de tâches courantes de l’API externe :
• Utilisation d’ActionScript pour appeler le code dans une page Web affichée dans un navigateur ou une application de bureau AIR
• Création d’un proxy pour simplifier l’appel de code ActionScript depuis une page Web Remarque : seule une communication entre ActionScript dans un fichier SWF et l’application conteneur qui comprend une référence à Flash Player ou à l’occurrence dans laquelle ce fichier SWF est chargé est passée en revue ci-après. Toute autre utilisation de Flash Player dans une application n’est pas traitée dans cette documentation. Flash Player est conçu pour être utilisé comme plug-in de navigation ou de projection (application autonome). Les autres scénarios d’utilisation peuvent avoir une prise en charge limitée. Utilisation de l’API externe dans AIR Etant donné qu’une application AIR ne possède pas de conteneur externe, l’interface externe n’est généralement ni utilisée, ni requise. Lorsque l’application AIR charge directement un fichier SWF, le code correspondant peut communiquer directement avec le code ActionScript dans le fichier SWF (conformément aux restrictions du sandbox de sécurité). Toutefois, lorsque l’application AIR charge un fichier SWF par le biais d’une page HTML dans un objet HTMLLoader (ou un composant HTML dans Flex), cet objet sert de conteneur externe. Le code ActionScript figurant dans le fichier SWF chargé peut ainsi communiquer avec le code JavaScript figurant dans la page HTML chargée dans l’objet HTMLLoader, par le biais de l’interface externe.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Même si, dans certains cas, un fichier SWF peut s’exécuter tout seul (si vous faites appel à Adobe® Flash® Professional pour créer un fichier de projection SWF, par exemple), une application SWF s’exécute généralement comme un élément intégré à une autre application. De façon générale, le conteneur dans lequel le fichier SWF est intégré est un fichier HTML ; un fichier SWF est utilisé, moins fréquemment, pour une partie ou l’intégralité de l’interface utilisateur d’une application de bureau.
Utilisation de l’API externe
Concepts importants et terminologie La liste de référence suivante contient des termes importants relatifs à cette fonctionnalité. Application conteneur Application au sein de laquelle Flash Player exécute un fichier SWF, notamment un navigateur
Fichier de projection Fichier exécutable qui comprend un contenu SWF et une version intégrée de Flash Player. Pour créer un fichier de projection, faites appel à Flash Professional ou à la version autonome de Flash Player. Les fichiers de projection sont généralement utilisés pour distribuer des fichiers SWF par CD-ROM ou dans des situations semblables, lorsque le volume à télécharger n’est pas un problème et que l’auteur du SWF souhaite être sûr que l’utilisateur pourra exécuter le fichier SWF, indépendamment du fait que Flash Player est installé sur l’ordinateur de l’utilisateur. Proxy Code ou application intermédiaire qui appelle du code dans une application (l’application externe) au nom d’une autre application (l’application appelante), et renvoie des valeurs à l’application appelante. Un proxy peut être utilisé pour différentes raisons, notamment :
Sérialiser Convertir des objets ou des valeurs de données en un format qui permet de transmettre les valeurs dans des
Utilisation des exemples La plupart des exemples sont des blocs de code de petite taille proposés à des fins de démonstration, plutôt que des exemples complets ou des codes qui vérifient des valeurs. Etant donné que l’utilisation de l’API externe exige (par définition) l’écriture de code ActionScript ainsi que de code dans une application conteneur, le test des exemples implique la création d’un conteneur (par exemple, une page Web contenant le fichier SWF) et l’utilisation des codes pour interagir avec le conteneur. Pour tester un exemple de communication entre ActionScript et JavaScript : 1 Créez un document vide à l’aide de Flash Professional et enregistrez-le dans votre ordinateur. 2 Dans le menu principal, choisissez Fichier > Paramètres de publication. 3 Dans l’onglet Formats de la boîte de dialogue Paramètres de publication, vérifiez que les cases à cocher Flash et
4 Cliquez sur le bouton Publier. Ceci génère un fichier SWF et un fichier HTML dans le même dossier et avec le même
ajouter le code JavaScript approprié. Lorsque vous désactivez l’option HTML, vous vous assurez qu’après avoir modifié la page HTML, Flash n’écrasera pas vos changements avec une nouvelle page HTML lors de la publication du fichier SWF. 6 Fermez la boîte de dialogue Paramètres de publication en cliquant sur le bouton OK. 7 Avec une application d’éditeur de texte ou HTML, ouvrez le fichier HTML créé par Flash lorsque vous avez publié
<script> // add the sample JavaScript code here 11 Dans le menu principal, choisissez Fichier > Publier pour mettre à jour le fichier SWF avec les changements que
12 Utilisez un navigateur Web pour ouvrir la page HTML que vous avez modifiée afin d’afficher la page et de tester la
Pour tester un exemple de communication de conteneur ActionScript-vers-ActiveX : 1 Créez un document vide à l’aide de Flash Professional et enregistrez-le dans votre ordinateur. Vous pouvez l’enregistrer dans le dossier dans lequel votre application conteneur s’attend à trouver le fichier SWF. 2 Dans le menu principal, choisissez Fichier > Paramètres de publication. 3 Dans l’onglet Formats de la boîte de dialogue Paramètres de publication, vérifiez que seule la case à cocher Flash est
4 Dans le champ Fichier situé en regard de la case à cocher Flash, cliquez sur l’icône de dossier pour sélectionner le
5 Sélectionnez l’image-clé sur l’image 1 du scénario puis ouvrez le panneau Actions. 6 Copiez le code ActionScript pour l’exemple dans le panneau Script. 7 Dans le menu principal, choisissez Fichier > Publier pour publier de nouveau le fichier SWF. 8 Créez et exécutez votre application conteneur afin de tester la communication entre elle et ActionScript.
Ces exemples comprennent le code entier (y compris le code ActionScript et de vérification des erreurs du conteneur) que vous devez utiliser lorsque vous écrivez le code à l’aide de l’API externe. Pour consulter un autre exemple complet d’utilisation de l’API externe, voir l’exemple associé à la classe ExternalInterface dans le Guide de référence ActionScript 3.0 pour Flash Professional.
L’API externe correspond à la partie d’ActionScript qui fournit le mécanisme de communication entre ActionScript et le code exécuté dans une application dite externe, c’est-à-dire qui joue le rôle de conteneur pour Flash Player (en général un navigateur Web ou une application de projection autonome). Dans ActionScript 3.0, la fonctionnalité de l’API externe est assurée par la classe ExternalInterface. Dans les versions de Flash Player antérieures à Flash Player 8, l’action fscommand() était utilisée pour établir les communications avec l’application conteneur. La classe ExternalInterface remplace l’action fscommand(). Remarque : si vous devez utiliser l’ancienne fonction fscommand() (par exemple pour maintenir la compatibilité avec d’anciennes applications ou pour interagir avec une application conteneur SWF tierce ou avec le lecteur autonome Flash Player), elle est disponible au niveau du package flash.system. La classe ExternalInterface est un sous-système permettant de communiquer facilement d’ActionScript et Flash Player à JavaScript dans une page HTML. La classe ExternalInterface est disponible uniquement dans les circonstances suivantes :
• Dans un navigateur qui prend en charge l’interface NPRuntime, qui actuellement comprend Firefox 1.0 et versions ultérieures, Mozilla 1.7.5 et versions ultérieures, Netscape 8.0 et versions ultérieures, ainsi que Safari 1.3 et versions ultérieures.
HTMLLoader. Dans tous les autres cas de figure (par exemple exécution dans un lecteur autonome), la propriété ExternalInterface.available renvoie la valeur false. Depuis ActionScript, vous pouvez appeler une fonction JavaScript sur la page HTML. L’API externe apporte les améliorations fonctionnelles suivantes grâce à fscommand() :
• Vous pouvez transmettre n’importe quel nombre d’arguments, avec n’importe quels noms ; vous n’êtes pas limité à une commande et une chaîne d’argument. L’API externe offre donc bien plus de souplesse que fscommand().
Important : si le nom attribué à l’occurrence de Flash Player sur une page HTML (l’attribut id de la balise object) contient un tiret (-) ou un autre caractère défini en tant qu’opérateur dans JavaScript (tels +, *, /, \, ., etc.), les appels à ExternalInterface effectués depuis ActionScript ne fonctionnent pas lorsque la page Web du conteneur est consultée dans Internet Explorer. En outre, si les balises HTML qui définissent l’occurrence de Flash Player (les balises object et embed) sont imbriquées dans une balise form HTML, les appels à ExternalInterface effectués depuis ActionScript ne fonctionnent pas.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La communication entre ActionScript et l’application conteneur peut se faire de deux façons : soit ActionScript appelle un élément de code (par exemple une fonction JavaScript) défini dans le conteneur, soit le code du conteneur appelle une fonction ActionScript définie comme pouvant être appelée. Dans les deux cas, des informations peuvent être envoyées au code appelé et les résultats renvoyés au code appelant. Pour faciliter la communication, la classe ExternalInterface comprend deux propriétés statiques et deux méthodes statiques également. Ces propriétés et méthodes servent à obtenir des informations sur la connexion à l’interface externe, à exécuter le code dans le conteneur à partir d’ActionScript et de rendre disponibles les fonctions ActionScript que le conteneur doit appeler.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La propriété ExternalInterface.available indique si Flash Player se trouve dans un conteneur offrant une interface externe. Si l’interface externe est disponible, cette propriété est true ; sinon, elle est false. Avant d’utiliser toute autre fonctionnalité de la classe ExternalInterface, vous devez toujours vérifier que le conteneur actif prend en charge la communication avec l’interface externe, comme suit : if (ExternalInterface.available) { // Perform ExternalInterface method calls here. } La propriété ExternalInterface.objectID vous permet de déterminer l’identifiant unique de l’occurrence Flash Player (c’est-à-dire, l’attribut id de la balise object dans Internet Explorer ou l’attribut name de la balise embed dans les navigateurs utilisant l’interface NPRuntime). Cet identifiant unique représente le document SWF actif dans le navigateur et permet d’y faire référence, par exemple si vous appelez une fonction JavaScript dans une page HTML conteneur. Si le conteneur Flash Player n’est pas un navigateur Web, la propriété est null.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La méthode ExternalInterface.call() exécute le code dans l’application conteneur. Elle nécessite au moins un paramètre, une chaîne contenant le nom de la fonction à appeler dans cette application. Tout paramètre supplémentaire transmis à la méthode ExternalInterface.call() est retransmis au conteneur comme paramètres de l’appel de fonction. // calls the external function "addNumbers" // passing two parameters, and assigning that function's result // to the variable "result" var param1:uint = 3; var param2:uint = 7; var result:uint = ExternalInterface.call("addNumbers", param1, param2); Que le conteneur soit un navigateur Web ou un autre conteneur ActiveX, si l’appel échoue ou que la méthode conteneur ne spécifie aucune valeur de retour, la valeur null est alors renvoyée. La méthode ExternalInterface.call() renvoie une exception SecurityError si l’environnement conteneur appartient à un sandbox de sécurité auquel le code appelant n’a pas accès. Vous pouvez contourner ce problème en attribuant à allowScriptAccess une valeur adaptée dans l’environnement conteneur. Par exemple, vous changez la valeur de allowScriptAccess dans une page HTML, vous devez modifier l’attribut approprié dans les balises object et embed.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Un conteneur peut uniquement appeler du code ActionScript compris dans une fonction, et aucun autre code ActionScript. Pour appeler une fonction ActionScript à partir de l’application conteneur, deux opérations sont nécessaires : enregistrer la fonction auprès de la classe ExternalInterface, puis l’appeler à partir du code du conteneur. Dans un premier temps, vous devez enregistrer votre fonction ActionScript pour indiquer qu’elle doit être mise à disposition du conteneur. Pour ce faire, utilisez la méthode ExternalInterface.addCallback() comme suit : function callMe(name:String):String { return "busy signal"; } ExternalInterface.addCallback("myFunction", callMe); à la page 880. Dans les deux cas, la valeur de retour de la fonction ActionScript est retransmise au code du conteneur, directement sous forme de valeur si l’appelant est un code JavaScript dans un navigateur ou sous forme de chaîne XML s’il s’agit d’un conteneur ActiveX.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La communication entre ActionScript et une application hébergeant le contrôle Active X Shockwave Flash nécessite un format XML spécifique qui servira à convertir les appels de fonction et les valeurs. Le format XML utilisé par l’API externe se divise en deux parties. L’une est destinée à représenter les appels de fonction. L’autre sert à représenter des valeurs individuelles ; ce format s’applique aux paramètres des fonctions comme aux valeurs de retour. Le format XML des appels de fonction est utilisé pour les appels en provenance et à destination d’ActionScript. Pour un appel de fonction issu d’ActionScript, Flash Player transmet les informations XML au conteneur ; pour un appel provenant du conteneur, Flash Player attend de l’application une chaîne XML du même format. L’extrait XML suivant donne un exemple d’appel de fonction formaté : <invoke name="functionName" returntype="xml"> <arguments> ... (individual argument values) Dernière mise à jour le 27/4/2013
Dernière mise à jour le 27/4/2013
• Appel des fonctions JavaScript à partir d’ActionScript, transmission des paramètres et réception des valeurs en retour
Pour obtenir les fichiers d’application de cet exemple, voir www.adobe.com/go/learn_programmingAS3samples_flash_fr. Les fichiers de l’application Introvert IM se trouvent dans le dossier Samples/IntrovertIM_HTML. L’application se compose des fichiers suivants : Fichier
L’API externe est le plus souvent utilisée pour permettre aux applications ActionScript de communiquer avec le navigateur Web. Grâce à elle, les méthodes ActionScript peuvent appeler du code écrit dans JavaScript, et inversement. En raison de la complexité des navigateurs et de leurs processus internes de rendu des pages, il est impossible de garantir qu’un document SWF pourra enregistrer ses rappels avant l’exécution du premier code JavaScript de la page HTML. Par conséquent, avant d’appeler les fonctions du document SWF à partir de JavaScript, le document SWF doit toujours appeler la page HTML pour lui indiquer qu’il est prêt à accepter des connexions.
Utilisation de l’API externe
{ _status = initialStatus; Le code appelle ensuite la méthode isContainerReady(), présentée ici : private function isContainerReady():Boolean { var result:Boolean = ExternalInterface.call("isReady"); return result; }
{ // Check if the container is now ready. var isReady:Boolean = isContainerReady(); if (isReady) Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Comme le montre l’exemple précédent, une fois que le code établit que le navigateur est prêt, la méthode setupCallbacks() est appelée. Cette méthode prépare ActionScript pour recevoir des appels à partir de JavaScript, comme le montre cet exemple : private function setupCallbacks():void { // Register the SWF client functions with the container ExternalInterface.addCallback("newMessage", newMessage); Dans ce code, le premier paramètre (le nom qui sert à désigner la méthode dans JavaScript, soit "newMessage" et "getStatus") est identique au nom de la méthode dans ActionScript (dans ce cas, il n’y avait pas d’intérêt à utiliser des noms différents, on a donc réutilisé les mêmes noms par souci de simplification). Enfin, la méthode ExternalInterface.call() est utilisée pour appeler la fonction JavaScript setSWFIsReady(), qui avertit le conteneur que les fonctions ActionScript ont été enregistrées.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’application Introvert IM met en évidence plusieurs exemples d’appel de fonctions JavaScript dans la page conteneur. Dans le cas le plus simple (un exemple issu de la méthode setupCallbacks()), la fonction JavaScript setSWFIsReady() est appelée sans transmettre de paramètres ni recevoir de valeur en retour : ExternalInterface.call("setSWFIsReady");
{ ExternalInterface.call("newMessage", message); Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Une communication se fait normalement de manière bidirectionnelle, ce que respecte l’application Introvert IM. D’un côté, le client de messagerie Flash Player appelle JavaScript pour envoyer des messages, de l’autre, le formulaire HTML appelle le code JavaScript pour envoyer des messages au fichier SWF et recevoir de celui-ci des informations. Par exemple, lorsque le fichier SWF avertit le conteneur qu’il a établi le contact et peut communiquer, la première action du navigateur consiste à appeler la méthode getStatus() de la classe IMManager pour recevoir du client de messagerie SWF le statut de disponibilité de l’utilisateur initial. Cela se fait dans la page Web, avec la fonction updateStatus(), comme illustré ci-après : <script language="JavaScript"> ... function updateStatus() { if (swfReady) SWF. Le paramètre transmis à getSWF() détermine si l’objet de navigateur est renvoyé, au cas où il y aurait plus d’un fichier SWF dans la page HTML. La valeur transmise à ce paramètre doit correspondre à l’attribut id de la balise object et à l’attribut name de la balise embed, toutes deux utilisées pour inclure le fichier SWF.
ActionScript a été enregistrée à l’aide de ExternalInterface.addCallback().
Remarque : si vous vous référez au code, vous avez probablement noté que dans le code source relatif à la fonction updateStatus(), la ligne qui appelle la fonction getSWF() est en fait écrite comme suit : var currentStatus = getSWF("${application}").getStatus(). Le texte ${application} est un espace réservé dans le modèle de page HTML. Lorsqu’Adobe Flash Builder génère la page HTML en tant que telle pour l’application, cet espace réservé est remplacé par le texte faisant office d’attribut id de la balise object et d’attribut name de la balise embed (soit IntrovertIMApp dans l’exemple). Il s’agit de la valeur attendue par la fonction getSWF(). La fonction JavaScript sendMessage() illustre la transmission d’un paramètre à la fonction ActionScript (sendMessage() est la fonction appelée lorsque l’utilisateur appuie sur le bouton Envoyer de la page HTML).
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures L’accès au contenu varie d’un navigateur à l’autre. Pour cette raison, il est important de toujours utiliser JavaScript pour détecter le navigateur utilisé et accéder ensuite à la séquence selon la syntaxe propre au navigateur à l’aide de l’objet de fenêtre ou de document, comme le montre la fonction JavaScript getSWF() de cet exemple : <script language="JavaScript"> ... function getSWF(movieName) { if (navigator.appName.indexOf("Microsoft") != -1) XML (http://www.w3.org/TR/xmldsig-core/). Des signatures XML peuvent être utilisées pour vérifier l’intégrité et l’identité du signataire des données ou des informations. Les signatures XML peuvent être utilisées pour valider les messages ou les ressources téléchargé(e)s par votre application. Par exemple, si votre application fournit des services sur la base d’un abonnement, vous pouvez encapsuler les termes de l’abonnement dans un document XML signé. Si quelqu’un tente de modifier le document d’abonnement, la validation échoue. Vous pouvez également utiliser une signature XML pour simplifier la validation des ressources téléchargées par votre application en incluant un fichier manifest signé contenant les digests de ces ressources. Votre application peut alors vérifier que les ressources n’ont pas été modifiées en comparant le digest du fichier signé et le digest calculé à partir des octets chargés. Cette technique se révèle particulièrement utile lorsque la ressource téléchargée est un fichier SWF ou un autre contenu actif à exécuter dans le sandbox de sécurité de l’application.
Pour obtenir une explication rapide de la validation des signatures XML, ainsi que des exemples de code correspondants, voir les articles de démarrage rapide suivants dans Adobe Developer Connection :
• Création et validation de signatures XML (Flash) (disponible en anglais uniquement) Adobe® AIR® fournit la classe XMLSignatureValidator et l’interface IURIDereferencer pour la validation des signatures XML. La syntaxe XML acceptée par la classe XMLSignatureValidator est un sous-ensemble de la recommandation du W3C portant sur la syntaxe et le traitement des signatures XML. (Comme seul un sous-ensemble de la recommandation est pris en charge, toutes les signatures valides ne peuvent pas être validées.) AIR ne fournit pas d’API capable de créer des signatures XML.
L’API de validation des signatures XML comprend les classes suivantes :
• Fournir une implémentation de l’interface IURIDereferencer. L’objet XMLSignatureValidator appelle la méthode IURIDereferencer dereference(), en transmettant l’URI pour chaque référence présente dans une signature. La méthode dereference() doit résoudre l’URI et renvoyer les données référencées (situées dans le même document que la signature ou dans une ressource externe).
• Appeler la méthode verify(), en transmettant la signature à vérifier. • Traiter les événements complete et error et interpréter les résultats. L’exemple suivant implémente une fonction validate() qui vérifie la validité d’une signature XML. Les propriétés XMLSignatureValidator sont définies de telle sorte que le certificat de signature doit être présent dans le magasin d’approbation du système, ou chaîné vers un certificat du magasin d’approbation. L’exemple suppose également l’existence d’une classe IURIDereferencer appropriée nommée XMLDereferencer.
• Le moteur d’exécution établie l’intégrité cryptographique, l’identité et la véracité du certificat sur la base des paramètres actuels de l’objet XMLSignatureValidator. La confiance accordée au certificat de signature est essentielle pour l’intégrité du processus de validation. La validation de la signature est effectuée via un processus cryptographique bien défini, mais la fiabilité du certificat de signature ne peut pas être assurée par un algorithme. En général, trois méthodes permettent de savoir si un certificat est fiable :
• Demander à l’utilisateur final de votre application s’il fait confiance au certificat. Une telle requête n’est pas valide pour les certificats auto-signés car les informations d’identification du certificat ne sont pas fiables par nature.
Les données signées sont vérifiées à l’aide de votre implémentation d’IURIDereferencer. Pour chaque référence du document de signature, la méthode dereference() de l’implémentation d’IURIDereferencer est appelée. Les données renvoyées par la méthode dereference() sont utilisées pour calculer le digest de référence. La valeur du digest est comparée au digest enregistré dans le document de signature. Si les digests correspondent, les données n’ont pas été modifiées depuis leur signature. Une considération importante lorsque l’on s’appuie sur les résultats de la validation d’une signature XML est que seul ce qui a été signé est sécurisé. Par exemple, prenons le cas de la liste signée des fichiers contenus dans un package. Lorsque XMLSignatureValidator vérifie la signature, l’opération s’assure uniquement que la liste ellemême n’a pas été modifiée. Les données des fichiers n’étant pas signées, la signature reste valide même si les fichiers référencés ont été modifiés ou supprimés. Remarque : pour vérifier les fichiers d’une telle liste, vous pouvez calculer le digest de leurs données (en utilisant le même algorithme de hachage que pour la liste) et comparer le résultat au digest stocké dans la liste signée. Dans certains cas, vous pouvez également vérifier la présence de fichiers supplémentaires.
Adobe AIR 1.5 et les versions ultérieures Les résultats de la validation sont indiqués par les propriétés d’état de l’objet XMLSignatureValidator. Ces propriétés peuvent être lues après la distribution de l’événement complete par l’objet validateur. Les quatre propriétés d’état sont : validityStatus, digestStatus, identityStatus et referencesStatus. Propriété validityStatus Adobe AIR 1.5 et les versions ultérieures La propriété validityStatus renvoie la validité générale de la signature. Cette propriété validityStatus dépend de l’état des trois autres propriétés d’état et peut prendre l’une des valeurs suivantes :
La propriété identityStatus renvoie l’état du certificat de signature. La valeur de cette propriété dépend de plusieurs facteurs :
• expiration ou révocation éventuelle du certificat ; • approbation du certificat sur l’ordinateur en cours ; • état de l’objet XMLSignatureValidator (par exemple, si des certificats supplémentaires ont été ajoutés pour définir la chaîne de confiance, si ces certificats sont approuvés, et valeurs des propriétés useSystemTrustStore et revocationCheckSettings). La propriété identityStatus peut avoir l’une des valeurs suivantes :
SignedData de la signature.
A propos des signatures XML Adobe AIR 1.5 et les versions ultérieures Une signature XML est une signature numérique représentée en syntaxe XML. Les données d’une signature XML peuvent être utilisées pour garantir la non modification des informations signées depuis la signature. De plus, lorsqu’un certificat de signature a été publié par une autorité de certification approuvée, l’identité du signataire peut être vérifiée via l’infrastructure de clé publique. Une signature XML peut être appliquée à n’importe quel type de données numériques (au format binaire ou XML). Des signatures XML sont généralement utilisées pour :
• vérifier que des messages proviennent d’une source connue ; • valider les droits de licence d’une application ou les droits d’abonnement.
Adobe AIR 1.5 et les versions ultérieures AIR prend en charge les éléments suivants de la recommandation W3C portant sur la syntaxe et le traitement des signatures :
• Un élément X509Data ne doit contenir qu’un élément X509Certificate. • La méthode digest SHA256 • L’algorithme de signature RSA-SHA1 (PKCS1) • La méthode de canonisation « XML canonique sans commentaires » et l’algorithme de transformation • La transformation de la signature enveloppée • horodatage Le document suivant présente une signature XML typique (la plupart des données cryptographiques ont été supprimées pour simplifier l’exemple) :
• SignatureValue : contient un digest de l’élément SignedInfo chiffré avec la clé privée du signataire. • KeyInfo : contient le certificat de signature et tout certificat supplémentaire nécessaire pour établir la chaîne d’approbation. Notez que, bien que l’élément KeyInfo soit techniquement facultatif, AIR ne peut pas valider la signature s’il n’est pas inclus. Il existe trois types généraux de signature XML :
• Enveloppante : les données XML signées sont incluses dans un élément Object au sein de l’élément Signature. • Détachée : les données signées sont externes à la signature XML. Les données signées doivent être dans un fichier externe. Elles peuvent également être dans le même document XML que la signature, mais pas dans un élément parent ou enfant de l’élément Signature. Pour référencer les données signées, les signatures XML utilisent des URI. Pour résoudre ces URI, les applications de signature et de validation doivent utiliser les mêmes conventions. Lorsque vous utilisez la classe XMLSignatureValidator, vous devez fournir une implémentation de l’interface IURIDereferencer. Cette implémentation est chargée de résoudre l’URI et de renvoyer les données signées sous forme d’objet ByteArray. Le digest de l’objet ByteArray renvoyé est calculé avec le même algorithme que celui qui a permis de calculer le digest de la signature.
Adobe AIR 1.5 et les versions ultérieures Un certificat est constitué d’une clé publique, d’informations d’identification et, éventuellement, d’un ou plusieurs certificats appartenant à l’autorité de certification émettrice.
Même si le certificat est publié par une autorité de certification approuvée, vous devez décider si le certificat appartient à une personne de confiance. Dans la plupart des cas, cette décision revient à l’utilisateur final. Par exemple, lors de l’installation d’une application AIR, le programme d’installation AIR affiche les informations d’identification du certificat de l’éditeur lorsqu’il invite l’utilisateur à indiquer s’il souhaite installer l’application. Dans d’autres cas, vous devrez peut-être comparer la clé publique ou d’autres informations de certificat à une liste de clés acceptables. (Cette liste doit être sécurisée, éventuellement par sa propre signature ou en étant stockée dans le magasin local chiffré d’AIR, de sorte que la liste elle-même ne puisse pas être altérée.) Remarque : bien que vous puissiez choisir d’approuver le certificat de signature sans vérification indépendante (par exemple lorsque une signature est « auto-signée »), la vérification de la signature n’est pas suffisamment rassurante dans ce cas. Si vous ne connaissez pas l’auteur de la signature, la certitude que la signature n’a pas été modifiée n’a que peu de valeur. La signature peut être une contrefaçon signée. Expiration et révocation des certificats Adobe AIR 1.5 et les versions ultérieures Tous les certificats arrivent à expiration à un moment donné. Les certificats peuvent également être révoqués par l’autorité de certification émettrice si, par exemple, la clé privée associée au certificat a été compromise ou volée. Si une signature est signée avec un certificat arrivé à expiration ou révoqué, elle est désignée comme non valide sauf si un horodatage a été inclus dans la signature. En présence d’un horodatage, la classe XMLSignatureValidator valide la signature si le certificat était valide au moment de la signature. Un horodatage est un message numérique signé provenant d’un service d’horodatage qui certifie que les données ont été signées à une heure et une date spécifiques. Les horodatages sont publiés par des autorités d’horodatage et signés par le propre certificat de ces autorités. Le certificat de l’autorité d’horodatage intégré à l’horodatage doit être approuvé sur l’ordinateur en cours pour que cet horodatage soit considéré comme valide. L’objet XMLSignatureValidator ne fournit pas d’API pour désigner un autre certificat à utiliser pour valider l’horodatage.
Adobe AIR 1.5 et les versions ultérieures Pour valider une signature XML, vous devez fournir une implémentation de l’interface IURIDereferencer. Cette implémentation est chargée de résoudre les URI spécifiées dans les éléments Reference d’un document de signature XML, puis de renvoyer les données pour que le digest puisse être calculé. Le digest calculé est comparé au digest de la signature pour déterminer si les données référencées ont été modifiées depuis la création de la signature. Remarque : les applications AIR de type HTML doivent importer une bibliothèque SWF contenant une implémentation ActionScript pour valider les signatures XML. L’interface IURIDereferencer ne peut pas être implémentée en JavaScript.
Dans la plupart des cas, vous devrez également ajouter des propriétés ou des méthodes permettant à votre objet déréférenceur de localiser les données référencées. Par exemple, si les données signées sont dans le même document que la signature, vous pouvez ajouter une variable de membre fournissant une référence au document XML. La méthode dereference() peut alors utiliser cette variable, ainsi que l’URI, pour localiser les données référencées. De la même façon, si les données signées sont situées dans un répertoire du système de fichiers local, la méthode dereference() peut avoir besoin d’une propriété fournissant le chemin conduisant à ce répertoire pour résoudre les fichiers référencés. L’objet XMLSignatureValidator repose entièrement sur l’objet déréférenceur pour interpréter les chaînes URI. Les règles standard du déréférencement des URI sont données dans la section 4.3.3 de la recommandation du W3C portant sur la syntaxe et le traitement des signatures XML.
Adobe AIR 1.5 et les versions ultérieures Lorsqu’une signature XML enveloppée est générée, ses éléments sont insérés dans les données signées. Par exemple, si vous signez le message suivant à l’aide d’une structure de signature enveloppée : <message> <data>...</data> </message> Lorsque les données signées sont dans le même document que la signature elle-même, les URI des références utilisent généralement la syntaxe XPath ou XPointer pour traiter les éléments signés. La recommandation du W3C portant sur la syntaxe et le traitement des signatures XML ne conseillant que cette syntaxe, il est préférable de baser votre implémentation sur les signatures que vous envisagez de rencontrer (et d’ajouter suffisamment de vérification d’erreur pour traiter intelligemment la syntaxe non prise en charge). La signature d’une application AIR est un exemple de signature enveloppante. Les fichiers de l’application sont répertoriés dans un élément Manifest. L’élément Manifest est traité dans l’attribut Reference URI à l’aide de la chaîne, « #PackageContents », qui fait référence à l’identifiant de l’élément Manifest : <Signature xmlns="http://www.w3.org/2000/09/xmldsig#" Id="PackageSignature"> <SignedInfo> <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n20010315"/> Dernière mise à jour le 27/4/2013
AIR ne comprend pas de fonction intégrée pour le calcul des digests SHA256, mais le kit SDK Flex comprend une classe d’utilitaires SHA256. Le kit SDK comprend également la classe d’utilitaires encodeurs Base64 très utile pour comparer le digest calculé au digest stocké dans une signature. L’exemple de fonction suivant lit et valide les fichiers d’un manifeste de package AIR : import mx.utils.Base64Encoder; import mx.utils.SHA256; private { var var var
Notez que la classe Flex SHA256 renvoie le digest sous la forme d’une chaîne de caractères hexadécimale. Cette chaîne doit être convertie en ByteArray contenant les octets représentés par la chaîne hexadécimale. Pour utiliser les classes mx.utils.SHA256 et Base64Encoder dans Flash CS4, vous pouvez localiser et copier ces classes dans le répertoire de développement de votre application ou compiler une bibliothèque SWF contenant les classes à l’aide du kit SDK Flex.
Adobe AIR 1.5 et les versions ultérieures Lorsqu’une URI fait référence à une ressource externe, les données doivent être accédées et chargées dans un objet ByteArray. Si l’URI contient une URL absolue, il s’agit simplement de lire un fichier ou de demander une URL. Si, comme dans la plupart des cas, l’URI contient un chemin relatif, votre implémentation IURIDereferencer doit permettre de résoudre les chemins conduisant aux fichiers signés. L’exemple suivant utilise un objet File initialisé lorsque l’occurrence de dereferencer est construite en tant que base de résolution des fichiers signés.
Au fur et à mesure que vous créez des applications plus avancées, il se peut que vous souhaitiez en savoir plus sur les systèmes d’exploitation de vos utilisateurs et leurs fonctions d’accès. Le package flash.system contient un ensemble de classes permettant d’accéder à des fonctions de niveau système telles que :
• Détermination des fonctionnalités de l’occurrence du moteur d’exécution Flash (tel que Flash® Player ou Adobe® AIR™) de l’utilisateur (taille de l’écran - résolution) et des fonctionnalités disponibles (audio MP3, par exemple)
• Interaction avec le conteneur du moteur d’exécution Flash (qui peut être une page HTML ou une application de conteneur)
Le package flash.system comprend aussi les classes IMEConversionMode et SecurityPanel. Ces classes contiennent des constantes statiques que vous pouvez utiliser avec les classes IME et de sécurité, respectivement. Concepts importants et terminologie La liste de référence suivante contient des termes importants : Système d’exploitation Programme principal qui est exécuté sur un ordinateur, dans lequel toutes les autres
Presse-papiers Conteneur du système d’exploitation qui contient du texte ou des éléments qui sont copiés ou coupés, et à partir duquel des éléments sont collés dans des applications. Domaine d’application Mécanisme permettant de séparer les classes utilisées dans différents fichiers SWF de façon à
Environnement du système client
Système client En termes de programmation, un client est la partie d’une application (ou l’application entière) exécutée sur un ordinateur et utilisée par un seul utilisateur. Le système client est le système d’exploitation sous-jacent sur l’ordinateur de l’utilisateur.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe System contient des méthodes et propriétés qui permettent d’interagir avec le système d’exploitation de l’utilisateur et de récupérer l’utilisation mémoire actuelle du moteur d’exécution. Les méthodes et propriétés de la classe System permettent aussi d’écouter les événements imeComposition, d’indiquer au moteur d’exécution de charger des fichiers texte externes à l’aide de la page de code active de l’utilisateur ou d’Unicode, ou de définir le contenu du Presse-papiers de l’utilisateur.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures En vérifiant la propriété System.totalMemory, vous pouvez déterminer la quantité de mémoire (en octets) que le moteur d’exécution utilise actuellement. Cette propriété vous permet de surveiller l’utilisation mémoire et d’optimiser vos applications en fonction de ses variations. Par exemple, si un effet visuel particulier utilise une importante quantité de mémoire, vous pouvez envisager de le modifier ou de le supprimer entièrement. La propriété System.ime est une référence à l’IME actuellement installé. Elle vous permet d’écouter les événements imeComposition (flash.events.IMEEvent.IME_COMPOSITION) à l’aide de la méthode addEventListener(). La troisième propriété dans la classe System est useCodePage. Si useCodePage est défini sur true, le moteur d’exécution utilise la page de code classique du système d’exploitation pour charger les fichiers texte externes. Si vous lui attribuez la valeur false, vous indiquez au moteur d’exécution d’interpréter le fichier externe au format Unicode. Si vous définissez System.useCodePage sur true, souvenez-vous que la page de code classique du système d’exploitation doit inclure les caractères utilisés dans votre fichier texte externe afin d’afficher le texte. Par exemple, si vous chargez un fichier texte externe contenant des caractères chinois, ceux-ci ne peuvent s’afficher sur un système qui utilise la page de code anglaise de Windows car elle ne comprend pas les caractères chinois. Pour que les utilisateurs puissent afficher les fichiers texte externes utilisés dans l’application, quelle que soit la plateforme, vous devez coder tous les fichiers texte externes en Unicode et conserver la valeur par défaut false de la propriété System.useCodePage. Le moteur d’exécution interprète ainsi le texte au format Unicode.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe System inclut une méthode appelée setClipboard() qui permet au moteur d’exécution Flash de placer une chaîne spécifique dans le Presse-papiers de l’utilisateur. Pour des raisons de sécurité, il n’existe pas de méthode Security.getClipboard() car elle donnerait la possibilité d’accéder aux dernières données copiées dans le Pressepapiers de l’utilisateur.
Dans AIR, un événement utilisateur est superflu si le code s’exécute dans le sandbox de l’application pour accéder au Presse-papiers.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La classe Capabilities permet aux développeurs de déterminer l’environnement dans lequel s’exécute l’application. A l’aide des diverses propriétés de la classe Capabilities, vous pouvez déterminer la résolution et la langue du système de l’utilisateur, savoir si ce système prend en charge les logiciels d’accessibilité et identifier la version du moteur d’exécution Flash actuellement installée. La vérification des propriétés de la classe Capabilities vous autorise à personnaliser votre application pour un fonctionnement optimal sur l’environnement de l’utilisateur. Par exemple, si vous vérifiez les propriétés Capabilities.screenResolutionX et Capabilities.screenResolutionY, vous pouvez déterminer la résolution d’affichage du système de l’utilisateur et décider de la taille de vidéo la plus appropriée. Vous pouvez aussi vérifier la propriété Capabilities.hasMP3 pour voir si le système de l’utilisateur prend en charge la lecture du format mp3 avant d’essayer de charger un fichier mp3 externe. Le code ci-après utilise une expression régulière pour analyser la version du moteur d’exécution Flash utilisée sur le client : var versionString:String = Capabilities.version; var pattern:RegExp = /^(\w*) (\d*),(\d*),(\d*),(\d*)$/; var result:Object = pattern.exec(versionString); if (result != null) { trace("input: " + result.input); trace("platform: " + result[1]); trace("majorVersion: " + result[2]); trace("minorVersion: " + result[3]); trace("buildNumber: " + result[4]); trace("internalBuildNumber: " + result[5]); } else { trace("Unable to match RegExp."); L’exemple CapabilitiesExplorer vous montre comment utiliser la classe flash.system.Capabilities pour déterminer les fonctions prises en charge par la version du moteur d’exécution Flash de l’utilisateur. Cet exemple étudie les techniques suivantes :
Pour obtenir les fichiers d’application de cet exemple, voir www.adobe.com/go/learn_programmingAS3samples_flash_fr. Les fichiers d’application CapabilitiesExplorer se trouvent dans le dossier Samples/CapabilitiesExplorer. Cette application se compose des fichiers suivants : Fichier
Le fichier CapabilitiesExplorer.mxml se charge de définir l’interface utilisateur de l’application CapabilitiesExplorer. Les capacités de la version du moteur d’exécution Flash de l’utilisateur sont affichées dans une occurrence du composant DataGrid sur la scène. Les capacités du navigateur sont également affichées si l’application est exécutée à partir d’un conteneur HTML et si l’API externe est disponible.
Environnement du système client
{ var dp:Array = CapabilitiesGrabber.getCapabilities(); capabilitiesGrid.dataProvider = dp; } Présentation de la classe CapabilitiesGrabber Flash Player 9 et les versions ultérieures La méthode statique getCapabilities() de la classe CapabilitiesGrabber ajoute chaque propriété de la classe flash.system.Capabilities dans un tableau (capDP). Elle appelle ensuite la méthode statique getBrowserObjects() de la classe CapabilitiesGrabber. La méthode getBrowserObjects() utilise l’API externe pour passer en boucle sur l’objet navigator du navigateur, qui contient les capacités du navigateur. La méthode getCapabilities() se présente comme suit : public static function getCapabilities():Array { var capDP:Array = new Array(); capDP.push({name:"Capabilities.avHardwareDisable", value:Capabilities.avHardwareDisable}); capDP.push({name:"Capabilities.hasAccessibility", value:Capabilities.hasAccessibility}); capDP.push({name:"Capabilities.hasAudio", value:Capabilities.hasAudio}); ... capDP.push({name:"Capabilities.version", value:Capabilities.version}); var navArr:Array = CapabilitiesGrabber.getBrowserObjects(); if (navArr.length > 0) { capDP = capDP.concat(navArr); Communication avec JavaScript Flash Player 9 et les versions ultérieures La dernière étape dans la construction de l’application CapabilitiesExplorer consiste à écrire le code JavaScript nécessaire au passage en boucle de chaque élément de l’objet navigator du navigateur et à l’ajout d’une paire nomvaleur dans un tableau temporaire. Le code de la méthode JavaScript JS_getBrowserObjects() dans le fichier container.html est le suivant :
ActionScript d’analyser facilement les données à l’aide de la classe URLVariables.
Pour obtenir une explication rapide de l’ouverture et de la fermeture d’une application AIR et des exemples de code correspondants, voir les articles de démarrage rapide suivants dans Adobe Developer Connection :
• Il utilise l’application comme une commande sur un shell de ligne de commande. • Il ouvre un type de fichier pour lequel cette application correspond à l’application d’ouverture définie par défaut. • (Mac OS X) Il clique sur l’icône de l’application sur la barre des tâches du Dock (que l’application soit en cours d’exécution ou non).
• Il invoque l’application via une URL.
Appel et fermeture d’une application AIR
<allowBrowserInvocation>true</allowBrowserInvocation> afin que les appels au navigateur aboutissent.)
NativeApplication Singleton. Afin de laisser à une application le temps de s’initialiser et d’enregistrer un écouteur d’événement, les événements invoke sont placés en file d’attente au lieu d’être ignorés. Dès qu’un écouteur est enregistré, tous les événements placés en file d’attente sont livrés. Remarque : lorsqu’une application est appelée au moyen de la fonction d’appel du navigateur, l’objet NativeApplication distribue un événement invoke uniquement si l’application n’est pas en cours d’exécution. Pour recevoir des événements invoke, appelez la méthode addEventListener() de l’objet NativeApplication (NativeApplication.nativeApplication). Lorsqu’un écouteur d’événement s’enregistre pour un événement invoke, il reçoit également tous les événements invoke survenus avant l’enregistrement. Les événements invoke placés en file d’attente sont distribués un par un dans un court laps de temps après le renvoi de l’appel à addEventListener(). Si un nouvel événement invoke se produit au cours de ce processus, il peut être distribué avant un ou plusieurs des événements placés en file d’attente. Ce placement des événements en file d’attente vous permet de gérer tous les événements invoke survenus avant l’exécution de votre code d’initialisation. Sachez que si, plus tard dans l’exécution (après l’initialisation de l’application), vous ajoutez un écouteur d’événement, celui-ci recevra toujours tous les événements invoke survenus depuis le lancement de l’application. Une seule occurrence d’une application AIR est lancée. Lorsqu’une application en cours d’exécution est à nouveau appelée, AIR distribue un nouvel événement invoke vers elle. C’est l’application AIR qui est chargée de répondre à un événement invoke et de prendre les mesures appropriées (comme l’ouverture d’une nouvelle fenêtre de document). Un objet InvokeEvent contient tous les arguments transmis à l’application, de même qu’un répertoire à partir duquel l’application a été appelée. Si l’application a été appelée via une association de type de fichier, le chemin d’accès complet au fichier est alors inclus dans les arguments de ligne de commande. De la même manière, si l’application a été appelée via une mise à jour, le chemin d’accès complet au fichier AIR de mise à jour est fourni. Lorsque plusieurs fichiers sont ouverts simultanément, un seul objet InvokeEvent est distribué sous Mac OS X. Chaque fichier est inclus dans le tableau arguments. Sous Windows et Linux, un objet InvokeEvent distinct est distribué pour chaque fichier. Votre application gère les événements invoke en enregistrant un écouteur avec son objet NativeApplication : NativeApplication.nativeApplication.addEventListener(InvokeEvent.INVOKE, onInvokeEvent);
Les arguments de ligne de commande associés à l’appel d’une application AIR sont livrés dans l’objet InvokeEvent distribué par l’objet NativeApplication. La propriété arguments d’un objet InvokeEvent contient un tableau des arguments transmis par le système d’exploitation suite à l’appel d’une application AIR. Si les arguments contiennent des chemins de fichiers relatifs, il est généralement possible de résoudre les chemins à l’aide de la propriété currentDirectory. Les arguments transmis à un programme AIR sont traités sous forme de chaînes délimitées par des espaces, à moins d’être placés entre guillemets doubles : Arguments
L’exemple suivant explique comment enregistrer des écouteurs pour l’événement invoke et comment gérer ce type d’événement. Dans cet exemple, tous les événements d’appel reçus sont consignés dans un journal et le répertoire actif ainsi que les arguments de ligne de commande sont affichés.
Il est possible de configurer le lancement automatique d’une application AIR au moment de la connexion de l’utilisateur actif en définissant la propriété NativeApplication startAtLogin sur true. Une fois ce paramètre défini, l’application est lancée automatiquement chaque fois que l’utilisateur se connecte. Elle continue à démarrer lors d’une connexion tant que le paramètre n’est pas défini sur false. Soit ce changement est effectué manuellement par l’utilisateur via le système d’exploitation, soit il survient suite à la désinstallation de l’application. Le lancement au moment de la connexion est un paramètre d’exécution. Le paramètre s’applique uniquement à l’utilisateur actif. L’application doit être installée pour que la propriété startAtLogin soit définie sur true. Une erreur est renvoyée si la propriété est définie alors que l’application n’est pas installée (suite à un lancement à l’aide d’ADL, par exemple). Remarque : l’application n’est pas lancée au démarrage du système informatique. Elle s’ouvre lorsque l’utilisateur se connecte. Pour déterminer si une application a démarré automatiquement ou si son lancement résulte d’une action utilisateur, vous pouvez examiner la propriété reason de l’objet InvokeEvent. Si la propriété est définie sur InvokeEventReason.LOGIN, l’application a démarré automatiquement. Pour d’autres chemins d’invocation, la propriété reason est définie comme suit :
La fonction d’appel du navigateur permet à un site Web de lancer une application AIR installée à partir du navigateur. L’appel du navigateur est uniquement autorisé si le fichier descripteur d’application définit allowBrowserInvocation sur true : <allowBrowserInvocation>true</allowBrowserInvocation>
Cette propriété est uniquement définie pour le contenu du sandbox de sécurité distant (pour le contenu d’un domaine réseau). Elle n’est pas définie pour un contenu figurant dans un sandbox de sécurité d’application ou local.
BrowserInvokeEvent. Utilisez ces données avec précaution dans toute opération délicate, telle que des API de chargement de code ou de fichier. Le niveau de risque varie en fonction de l’usage que l’application réserve aux données. Si seul un site Web spécifique doit appeler l’application, celle-ci doit vérifier la propriété securityDomain de l’objet BrowserInvokeEvent. Vous pouvez également exiger de la part du site Web appelant l’application qu’il utilise le protocole HTTPS, ce que vous pouvez contrôler en vérifiant la propriété isHTTPS de l’objet BrowserInvokeEvent. L’application devrait valider les données transmises. Si, par exemple, une application s’attend à recevoir des URL pointant vers un domaine spécifique, elle devrait vérifier que les URL pointent réellement vers le domaine attendu. Cette procédure peut empêcher un pirate de tromper l’application en lui demandant de lui envoyer des données sensibles.
• En fermant la dernière fenêtre de l’application lorsque la méthode NativeApplication.nativeApplication.autoExit est définie sur true.
Lorsqu’une commande de fermeture est traitée par le biais du système d’exploitation selon l’une de ces méthodes, NativeApplication distribue un événement exiting. Si aucun écouteur n’annule l’événement exiting, toutes les fenêtres qui étaient ouvertes se ferment. Chaque fenêtre distribue un événement closing suivi d’un événement close. Si l’une des fenêtres annule l’événement closing, le processus d’arrêt est interrompu. Si l’ordre de fermeture des fenêtres présente un problème pour votre application, écoutez l’événement exiting de NativeApplication et fermez manuellement les fenêtres dans l’ordre approprié. Tel est par exemple le cas lorsqu’une fenêtre de document contient des palettes d’outils. Il peut s’avérer peu pratique (voire pire) que le système ferme les palettes alors que l’utilisateur a choisi d’annuler la commande de fermeture afin d’enregistrer des données. Sous Windows, vous obtiendrez uniquement l’événement exiting après la fermeture de la dernière fenêtre (lorsque la propriété autoExit de l’objet NativeApplication est définie sur true). Pour adopter un comportement homogène sur toutes les plates-formes, que la séquence de fermeture soit lancée via le chrome du système d’exploitation, les commandes de menu ou la logique de l’application, suivez les recommandations ci-après pour fermer l’application : 1 Distribuez toujours un événement exiting par le biais de l’objet NativeApplication avant d’appeler exit() dans
Si l’ordre de fermeture des fenêtres est sans importance, vous pouvez analyser en boucle le tableau NativeApplication.nativeApplication.openedWindows et fermer chaque fenêtre une après l’autre. Si l’ordre de fermeture compte, élaborez un moyen de l’appliquer aux fenêtres. private function onExiting(exitingEvent:Event):void { var winClosingEvent:Event; for each (var win:NativeWindow in NativeApplication.nativeApplication.openedWindows) { winClosingEvent = new Event(Event.CLOSING,false,true); win.dispatchEvent(winClosingEvent); if (!winClosingEvent.isDefaultPrevented()) { win.close(); } else { exitingEvent.preventDefault(); } } if (!exitingEvent.isDefaultPrevented()) { Les associations entre votre application et un type de fichier doivent être déclarées dans le descripteur d’application. Au cours du processus d’installation, le programme d’installation de l’application AIR spécifie celle-ci comme application de démarrage par défaut pour chacun des types de fichiers déclarés, à moins qu’une autre application ne le soit déjà par défaut. Le processus d’installation de l’application AIR n’écrase pas une association de types de fichiers existants. Pour remplacer l’association par une autre application, appelez la méthode NativeApplication.setAsDefaultApplication() lors de l’exécution. Il est recommandé de s’assurer que les associations de fichiers prévues sont en place lorsque votre application démarre. Ceci, parce que le programme d’installation de l’application AIR n’annule pas les associations de fichiers existantes et que ces associations sur un système d’utilisateur peuvent changer à tout moment. Lorsqu’une autre application dispose de l’association de fichiers actuelle, il est recommandé par courtoisie de demander une autorisation à l’utilisateur avant de prendre le contrôle de l’association en cours. Les méthodes suivantes de la classe NativeApplication permettent à une application de gérer des associations de fichiers. Chacune des méthodes prend l’extension du type de fichier comme paramètre. Méthode
AIR ne peut gérer des associations que pour des types de fichiers déclarés à l’origine dans le descripteur d’application. Il n’est pas possible de lire des informations sur les associations d’un type de fichier non déclaré, même si un utilisateur a créé manuellement l’association entre ce type de fichier et votre application. L’appel de toute méthode de gestion d’association de fichiers avec l’extension, pour un type de fichier non déclaré dans le descripteur d’application, provoque le renvoi d’une exception d’exécution par l’application
Adobe AIR 1.0 et les versions ultérieures L’ objet NativeApplication possède une propriété runtimeVersion, qui correspond à la version du moteur d’exécution dans lequel l’application est exécutée (une chaîne telle que "1.0.5"). L’objet NativeApplication possède également une propriété runtimePatchLevel qui est un niveau du correctif pour le moteur d’exécution, un nombre tel que 2960. Le code ci-dessous utilise ces propriétés : trace(NativeApplication.nativeApplication.runtimeVersion); trace(NativeApplication.nativeApplication.runtimePatchLevel);
Pour un fichier regroupé avec l’application Adobe AIR, la propriété Security.sandboxType est définie sur la valeur spécifiée par la constante Security.APPLICATION. Vous pouvez charger le contenu, qui peut contenir ou non des interfaces de programmation spécifiques à AIR, selon qu’un fichier se trouve ou non dans le sandbox de sécurité d’Adobe Air, comme le montre le code ci-dessous : if (Security.sandboxType == Security.APPLICATION) { // Load SWF that contains AIR APIs } else Pour plus d’informations, voir « Sécurité AIR » à la page 1122.
Suivi de la présence des utilisateurs Adobe AIR 1.0 et les versions ultérieures L’objet NativeApplication distribue deux événements qui vous aident à détecter à quel moment un utilisateur est actif sur son ordinateur. Si aucune activité de souris ou de clavier n’est détectée dans l’intervalle fixé par la propriété NativeApplication.idleThreshold, la NativeApplication distribue un événement userIdle. Lorsque survient l’entrée suivante par le clavier ou par la souris, l’objet NativeApplication distribue un événement userPresent. L’intervalle idleThreshold est mesuré en secondes et il a une valeur par défaut de 300, soit cinq minutes. Vous pouvez également lire le nombre de secondes depuis la dernière saisie de l’utilisateur grâce à la propriété NativeApplication.nativeApplication.lastUserInput. Les lignes de code ci-dessous définissent le délai d’inactivité sur deux minutes et elles sont à l’écoute des deux événements userIdle et userPresent : NativeApplication.nativeApplication.idleThreshold = 120; NativeApplication.nativeApplication.addEventListener(Event.USER_IDLE, function(event:Event) { trace("Idle"); }); Pour obtenir une explication rapide de l’utilisation des fenêtres natives dans AIR et des exemples de code correspondants, voir les articles de démarrage rapide suivants dans Adobe Developer Connection :
• Interaction avec une fenêtre (Flex) • Personnalisation de l’aspect d’une fenêtre native (Flex) • Démarrage de fenêtres (Flex) • Création de fenêtres affichées l’une derrière l’autre (Flex) • Contrôle de l’ordre d’affichage des fenêtres (Flex) • Création de fenêtres redimensionnables et non rectangulaires (Flex) • Interaction avec une fenêtre (Flash) • Personnalisation de l’aspect d’une fenêtre native (Flash) • Création de fenêtres affichées l’une derrière l’autre (Flash) • Contrôle de l’ordre d’affichage des fenêtres (Flash) • Création de fenêtres redimensionnables et non rectangulaires (Flash) AIR offre une API multiplateformes facile à utiliser vous permettant de créer des fenêtres natives dans un système d’exploitation à l’aide de Flash®, Flex™ et des techniques de programmation HTML. Grâce à AIR, vous pouvez personnaliser l’aspect de votre application en toute liberté. Les fenêtres que vous créez peuvent ressembler à une application de bureau standard, en reproduisant le style Apple lors d’une exécution sous Mac, en respectant les conventions Microsoft lors d’une exécution sous Windows, et en s’harmonisant au gestionnaire de fenêtres sous Linux, sans inclure une seule ligne de code spécifique à une plate-forme. Vous pouvez par ailleurs utiliser le chrome extensible, auquel il est possible d’appliquer une enveloppe, fourni par la structure d’application Flex afin de créer votre propre style, quelle que soit la plate-forme d’exécution de votre application. Vous pouvez de surcroît concevoir votre propre chrome de fenêtre avec des vecteurs et des images bitmap, et utiliser les effets de transparence, ainsi que le fondu alpha avec le poste de travail. Vous en avez assez des fenêtres rectangulaires ? Créez des fenêtres arrondies !
AIR prend en charge trois API distinctes pour l’utilisation des fenêtres :
NativeWindow dans les applications programmées dans ActionScript et Flash Professional. Pensez à étendre la classe NativeWindow pour spécialiser les fenêtres utilisées dans votre application.
Web à base de navigateur. Les appels aux méthodes Window de JavaScript sont transmis à l’objet window natif sous-jacent.
NativeWindow. Le composant WindowedApplication remplace le composant Application lorsque vous créez une application AIR avec Flex et doit toujours être utilisé comme fenêtre initiale dans votre application Flex. Fenêtres ActionScript Lorsque vous créez des fenêtres avec la classe NativeWindow, utilisez directement la scène et la liste d’affichage de Flash Player. Pour ajouter un objet visuel à une classe NativeWindow, ajoutez l’objet à la liste d’affichage de la scène de la fenêtre ou à un autre conteneur d’objet d’affichage sur la scène. Fenêtres HTML Lorsque vous créez des fenêtres HTML, utilisez HTML, CSS et JavaScript pour afficher du contenu. Pour ajouter un objet visuel à une fenêtre HTML, ajoutez ce contenu au DOM HTML. Les fenêtres HTML sont une catégorie spéciale de l’élément NativeWindow. L’hôte AIR définit une propriété nativeWindow dans les fenêtres HTML, qui fournit l’accès à l’occurrence de NativeWindow sous-jacente. Utilisez cette propriété pour accéder aux propriétés, méthodes et événements de l’élément NativeWindow décrits ici. Remarque : l’objet Window de JavaScript dispose également de méthodes pour la rédaction de scripts dans la fenêtre conteneur, telles que moveTo() et close(). Lorsque plusieurs méthodes sont disponibles, utilisez celle qui vous convient le mieux. Fenêtres de la structure d’application Flex Lorsque vous créez des fenêtres avec la structure d’application Flex, vous utilisez normalement des composants MXML pour remplir la fenêtre. Pour ajouter un composant Flex à une fenêtre, ajoutez l’élément de composant à la définition MXML de la fenêtre. Vous pouvez également utiliser ActionScript pour ajouter du contenu de façon dynamique. Les composants mx:WindowedApplication et mx:Window sont conçus comme conteneurs Flex et peuvent par conséquent accepter directement les composants Flex, ce que les objets NativeWindow ne permettent pas. Le cas échéant, il est possible d’accéder aux propriétés et méthodes NativeWindow par le biais des objets WindowedApplication et Window à l’aide de la propriété nativeWindow. La fenêtre initiale de l’application AIR crée pour vous la première fenêtre de l’application. AIR définit les propriétés et le contenu de la fenêtre à l’aide des paramètres spécifiés dans l’élément initialWindow du fichier descripteur d’application. Si le contenu racine est un fichier SWF, AIR crée une occurrence de NativeWindow, charge le fichier SWF et l’ajoute à la scène de la fenêtre. Si le contenu racine est un fichier HTML, AIR crée une fenêtre HTML et charge le fichier HTML.
1 L’objet NativeWindow distribue un événement displayStateChanging. 2 Si aucun écouteur enregistré n’annule l’événement, la fenêtre est agrandie. 3 L’objet NativeWindow distribue un événement displayStateChange.
Les événements associés sont les suivants : a Un événement move est distribué si le coin supérieur gauche de la fenêtre s’est déplacé suite à un agrandissement. b Un événement resize est distribué si la taille de la fenêtre a changé suite à un agrandissement.
Les événements d’avertissement ne sont distribués que lorsqu’une modification est initiée via le chrome de la fenêtre ou un autre mécanisme contrôlé par le système d’exploitation. Lorsque vous appelez une méthode window pour modifier la taille, la position ou l’état d’affichage de la fenêtre, la fenêtre ne distribue qu’un seul événement pour annoncer la modification. Vous pouvez distribuer un événement d’avertissement, si vous le souhaitez, à l’aide de la méthode dispatchEvent() de la fenêtre, puis vérifier si votre événement d’avertissement a été annulé avant d’effectuer la modification.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les propriétés suivantes contrôlent l’aspect et le comportement de base d’une fenêtre :
Adobe AIR 1.0 et les versions ultérieures Les types de fenêtres d’AIR combinent les attributs de chrome et de visibilité du système d’exploitation natif pour créer trois types de fenêtre fonctionnels. Utilisez les constantes définies dans la classe NativeWindowType pour référencer les noms des types de fenêtre dans le code. AIR fournit les types de fenêtre suivants : Type
Chrome de la fenêtre Adobe AIR 1.0 et les versions ultérieures Le chrome d’une fenêtre est un ensemble de commandes qui permet aux utilisateurs de manipuler une fenêtre dans l’environnement de bureau. Le chrome comprend les éléments suivants : barre de titre, boutons de la barre de titre, encadrement et poignées de redimensionnement.
NativeWindowSystemChrome pour référencer les paramètres du chrome système dans le code. Le chrome système est géré par le système. Votre application ne bénéficie pas d’un accès direct aux commandes, mais peut réagir aux événements distribués lorsque les commandes sont utilisées. Lorsque vous utilisez le chrome standard pour une fenêtre, la propriété transparent doit être définie sur false et la propriété type doit être définie sur normal ou sur utility. Chrome Flex Lorsque vous utilisez les composants WindowedApplication ou Window de Flex, la fenêtre peut faire appel soit au chrome système, soit au chrome fourni par la structure d’application Flex. Pour utiliser le chrome Flex, définissez la propriété systemChrome requise pour créer la fenêtre sur none. Si vous utilisez les composants spark de Flex 4 au lieu des composants mx, vous devez spécifier la classe d’enveloppe pour faire appel au chrome de Flex. Libre à vous de faire appel aux enveloppes intégrées ou à vos propres enveloppes. L’exemple suivant illustre l’utilisation de la classe d’enveloppe WindowedApplication des composants spark intégrée pour proposer le chrome de fenêtre : <?xml version="1.0" encoding="utf-8"?> <s:WindowedApplication xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark" xmlns:mx="library://ns.adobe.com/flex/mx"> Pour utiliser un chrome personnalisé avec le composant mx:WindowedApplication ou mx:Window, vous devez définir le style showFlexChrome sur false. Si tel n’est pas le cas, Flex intègre son propre chrome à vos fenêtres.
Adobe AIR 1.0 et les versions ultérieures Pour permettre le fondu alpha d’une fenêtre avec le bureau ou d’autres fenêtres, définissez la propriété transparent de la fenêtre sur true. La propriété transparent, qui doit être définie avant de créer la fenêtre, ne peut pas être modifiée. Une fenêtre transparente ne dispose d’aucun arrière-plan par défaut. Les zones d’une fenêtre qui ne contiennent aucun objet créé par l’application sont invisibles. Si le paramètre alpha d’un objet affiché est inférieur à un, tout élément affiché sous l’objet apparaît, notamment les autres objets d’affichage de la fenêtre, les autres fenêtres et le bureau.
Important : sous Linux, les événements de souris ne passent pas à travers des pixels entièrement transparents. Évitez de créer des fenêtres comprenant de vastes zones entièrement transparentes car vous pourriez bloquer de façon invisible l’accès de l’utilisateur aux autres fenêtres ou aux autres éléments de son bureau. Sous Mac OS X et Windows, les événements de souris passent à travers les pixels entièrement transparents. La transparence ne peut pas être utilisée avec des fenêtres disposant d’un chrome système. En outre, le contenu SWF et PDF dans HTML risque de ne pas s’afficher dans des fenêtres transparentes. Pour plus d’informations, voir « Eléments à prendre en compte lors du chargement d’un contenu SWF ou PDF dans une page HTML » à la page 1045. La propriété statique NativeWindow.supportsTransparency indique si la transparence de la fenêtre est disponible. Si la transparence n’est pas prise en charge, l’application utilise un arrière-plan noir. Dans ce cas, les zones transparentes de l’application s’affichent en noir opaque. Il est recommandé de proposer une solution de remplacement au cas où cette propriété serait définie sur false. Vous pourriez ainsi montrer une boîte de dialogue d’avertissement à l’utilisateur ou afficher une interface utilisateur rectangulaire et non transparente. Notez que la transparence est toujours prise en charge par les systèmes d’exploitation Mac et Windows. La prise en charge sur les systèmes d’exploitation Linux requiert un gestionnaire de composition de fenêtres. Cependant, même lorsqu’un tel gestionnaire est disponible, la transparence peut ne pas être disponible du fait des options d’affichage de l’utilisateur ou de sa configuration matérielle.
Par défaut, l’arrière-plan d’une fenêtre MXML est opaque, même si vous créez la fenêtre à l’aide de la propriété transparent. (Notez l’effet de transparence aux coins de la fenêtre.) Pour présenter un arrière-plan transparent pour la fenêtre, définissez une couleur d’arrière-plan et une valeur alpha dans la feuille de style ou l’élément <mx:Style> contenu dans le fichier MXML de votre application. Par exemple, la déclaration de style suivante confère à l’arrièreplan une nuance de vert légèrement transparente : WindowedApplication { background-alpha:".8"; background-color:"0x448234"; } L’appartenance des fenêtres permet de simplifier la gestion des fenêtres servant de palettes d’outils ou de boîtes de dialogue. Supposons, par exemple, que vous affichiez une boîte de dialogue d’enregistrement en conjonction avec une fenêtre de document. Si la boîte de dialogue appartient à la fenêtre de document, elle s’affiche automatiquement devant la fenêtre de document.
• Christian Cantrel: Owned windows in AIR 2.6 (disponible en anglais uniquement)
AIR crée automatiquement la première fenêtre d’une application, mais vous pouvez créer autant de fenêtres supplémentaires que vous le souhaitez. Pour créer une fenêtre native, utilisez la méthode constructeur NativeWindow. Pour créer une fenêtre HTML, utilisez la méthode createRootWindow() de l’objet HTMLLoader ou appelez la méthode JavaScript window.open() depuis un document HTML. La fenêtre créée est un objet NativeWindow dont la liste d’affichage contient un objet HTMLLoader. L’objet HTMLLoader interprète et affiche le contenu HTML et JavaScript associé à la fenêtre. Vous pouvez accéder aux propriétés de l’objet NativeWindow sous-jacent à partir de JavaScript par le biais de la propriété window.nativeWindow. (Cette propriété est réservée au code qui s’exécute dans le sandbox d’application AIR.) Lorsque vous initialisez une fenêtre, y compris la fenêtre d’application initiale, il peut s’avérer utile de la créer dans l’état invisible, de charger un contenu ou d’exécuter toute mise à jour graphique, puis d’activer la visibilité de la fenêtre. Cette séquence permet d’éviter que l’utilisateur visualise toute modification visuelle peu judicieuse. Pour stipuler que la fenêtre initiale de l’application doit être créée dans l’état invisible, spécifiez la balise <visible>false</visible> dans le descripteur d’application (ou omettez complètement la balise, puisque false est la valeur par défaut). Les nouvelles fenêtres NativeWindows sont invisibles par défaut. Lorsque vous créez une fenêtre HTML par le biais de la méthode createRootWindow() de la classe HTMLLoader, vous pouvez définir l’argument visible sur false. Appelez la méthode activate() de NativeWindowmethod ou définissez la propriété visible sur true pour activer la visibilité d’une fenêtre.
Adobe AIR 1.0 et les versions ultérieures Une fois la fenêtre du bureau créée, il est impossible de modifier les propriétés d’initialisation d’une fenêtre native. Ces propriétés immuables et leurs valeurs par défaut sont les suivantes : Propriété
Le code suivant crée un objet NativeWindowInitOptions pour une fenêtre d’utilitaire : var options:NativeWindowInitOptions = new NativeWindowInitOptions(); options.systemChrome = NativeWindowSystemChrome.STANDARD; options.type = NativeWindowType.UTILITY options.transparent = false; options.resizable = false; options.maximizable = false;
Remarque : vous ne pouvez pas définir les propriétés d’initialisation d’une fenêtre créée avec la fonction window.open() de JavaScript. Vous pouvez toutefois passer outre la méthode de création de ces fenêtres en implémentant votre propre classe HTMLHost. Pour plus d’informations, voir la section « Traitement des appels JavaScript à window.open() » à la page 1057. Lorsque vous créez une fenêtre à l’aide de la classe mx:Window de Flex, définissez les propriétés d’initialisation sur l’objet window en tant que tel, soit dans la déclaration MXML de la fenêtre, soit dans le code qui crée la fenêtre. L’objet NativeWindow sous-jacent n’est pas créé tant que vous n’avez pas appelé la méthode open(). Après avoir ouvert une fenêtre, il est impossible de modifier ces propriétés d’initialisation.
Adobe AIR 1.0 et les versions ultérieures AIR crée la fenêtre initiale de l’application en fonction des propriétés spécifiées dans le fichier descripteur d’application et charge le fichier référencé dans l’élément de contenu. L’élément de contenu doit faire référence à un fichier SWF ou HTML. La fenêtre initiale peut être la fenêtre principale de votre application, ou permettre simplement de lancer une ou plusieurs autres fenêtres. Il n’est absolument pas nécessaire de rendre cette fenêtre visible.
Adobe AIR 1.0 et les versions ultérieures Lorsque vous créez une application AIR à l’aide d’ActionScript, la classe principale de votre application doit étendre la classe Sprite (ou une sous-classe de cette dernière). Cette classe sert de point d’entrée principal à l’application. Lorsque votre application s’ouvre, AIR crée une fenêtre, crée une occurrence de la classe principale, puis ajoute l’occurrence à la scène de la fenêtre. Pour accéder à la fenêtre, vous pouvez écouter l’événement addedToStage, puis utiliser la propriété nativeWindow de l’objet Stage pour obtenir une référence à l’objet NativeWindow. L’exemple suivant illustre le squelette de base de la classe principale d’une application AIR créée avec ActionScript :
Création de la fenêtre initiale à l’aide de Flex Adobe AIR 1.0 et les versions ultérieures Lorsque vous créez une application AIR à l’aide de la structure d’application Flex, utilisez mx:WindowedApplication comme élément racine de votre fichier MXML principal. (Vous pouvez utiliser le composant mx:Application, mais il ne prend pas en charge toutes les fonctionnalités intégrées à AIR.) Le composant WindowedApplication sert de point d’entrée initial à l’application. Lorsque vous lancez l’application, AIR crée une fenêtre native, initialise la structure d’application Flex et ajoute l’objet WindowedApplication à la scène de la fenêtre. Une fois la séquence de lancement terminée, l’objet WindowedApplication distribue un événement applicationComplete. Accédez à l’objet de la fenêtre du bureau avec la propriété nativeWindow de l’occurrence de WindowedApplication. L’exemple suivant crée un composant WindowedApplication simple qui définit ses coordonnées x et y :
La fenêtre ne s’affiche pas tant que vous ne définissez pas la propriété visible sur true ou tant que vous n’appelez pas la méthode activate(). Une fois la fenêtre créée, vous pouvez initialiser ses propriétés et charger le contenu dans la fenêtre à l’aide de la propriété stage et des techniques de la liste d’affichage de Flash. Dans la plupart des cas, vous devez définir la propriété scaleMode de la scène d’une nouvelle fenêtre native sur noScale (utilisez la constante StageScaleMode.NO_SCALE). Les modes d’échelle de Flash sont conçus pour des
Le mode d’échelle pour Flex et les fenêtres HTML est automatiquement défini sur noScale. Remarque : pour déterminer les tailles maximale et minimale des fenêtres disponibles sur le système d’exploitation, utilisez les propriétés NativeWindow statiques suivantes : var maxOSSize:Point = NativeWindow.systemMaxSize; var minOSSize:Point = NativeWindow.systemMinSize;
Pour créer une fenêtre HTML, vous pouvez appeler la méthode Window.open() de JavaScript ou appeler la méthode createRootWindow() de la classe HTMLLoader d’AIR.
Remarque : vous pouvez étendre la classe HTMLHost dans ActionScript pour personnaliser la fenêtre créée avec la fonctionnalité window.open() de JavaScript. Voir la section « A propos de l’extension de la classe HTMLHost » à la page 1049. Le contenu du sandbox de sécurité de l’application a accès à la méthode de création de fenêtres la plus performante : HTMLLoader.createRootWindow(). Cette méthode vous permet de spécifier toutes les options de création d’une nouvelle fenêtre. Par exemple, le code JavaScript suivant crée un type de fenêtre légère sans chrome système, d’une taille de 300x400 pixels : var options = new air.NativeWindowInitOptions(); options.systemChrome = "none"; options.type = "lightweight"; var windowBounds = new air.Rectangle(200,250,300,400); newHTMLLoader = air.HTMLLoader.createRootWindow(true, options, true, windowBounds); newHTMLLoader.load(new air.URLRequest("xmpl.html"));
Si vous créez une fenêtre transparente, le contenu SWF intégré au code HTML chargé dans cette fenêtre ne s’affiche pas systématiquement. Vous devez définir le paramètre wmode de l’objet ou de la balise embed qui fait référence au fichier SWF sur opaque ou transparent. Etant donné que la valeur par défaut de wmode est window, le contenu SWF ne s’affiche par défaut pas dans une fenêtre transparente. Un contenu PDF ne s’affiche pas dans une fenêtre transparente, quelle que soit la valeur définie de wmode. (Dans les versions d’AIR antérieures à 1.5.2, il était également d’impossible d’afficher un contenu SWF dans une fenêtre transparente.) Les fenêtres créées avec la méthode createRootWindow() restent indépendantes de la fenêtre d’ouverture. Les propriétés parent et opener de l’objet Window de JavaScript sont définies sur null. La fenêtre d’ouverture peut accéder à l’objet Window de la nouvelle fenêtre à l’aide de la référence HTMLLoader renvoyée par la fonctionnalité createRootWindow(). Dans le cadre de l’exemple précédent, l’instruction newHTMLLoader.window référencerait l’objet Window de JavaScript de la fenêtre créée. Remarque : la fonctionnalité createRootWindow() peut être appelée depuis JavaScript et ActionScript.
Adobe AIR 1.0 et les versions ultérieures Pour créer un composant mx:Window, vous pouvez créer un fichier MXML à l’aide de mx:Window comme balise racine ou appeler directement le constructeur de la classe Window. L’exemple suivant crée et affiche un composant mx:Window en appelant le constructeur Window :
La méthode d’ajout de contenu à une fenêtre AIR dépend du type de fenêtre. Ainsi, MXML et HTML vous permettent de définir d’une manière déclarative le contenu de base de la fenêtre. Vous pouvez intégrer des ressources dans les fichiers SWF de l’application ou les charger à partir de fichiers d’application distincts. Le contenu Flex, Flash et HTML peut être créé au moment opportun et ajouté à la fenêtre de façon dynamique. Lorsque vous chargez du contenu SWF ou du contenu HTML contenant JavaScript, vous devez tenir compte du modèle de sécurité d’AIR. Le contenu dans le sandbox de sécurité de l’application, c’est-à-dire le contenu installé avec votre application et pouvant être chargé avec le modèle d’URL app:, dispose de privilèges complets pour accéder à toutes les API d’AIR. Le contenu chargé hors de ce sandbox ne peut pas accéder aux API d’AIR. Le contenu JavaScript hors du sandbox de l’application ne peut pas utiliser les propriétés runtime, nativeWindow et htmlLoader de l’objet Window de JavaScript. Pour sécuriser la programmation croisée, vous pouvez utiliser un pont de sandbox afin de fournir une interface limitée entre le contenu applicatif et le contenu hors application. Dans le contenu HTML, vous pouvez également mapper les pages de votre application sur un sandbox hors application afin que le code sur cette page puisse intercoder le contenu externe. Voir le chapitre « Sécurité AIR » à la page 1122. Chargement d’une image ou d’un fichier SWF Vous pouvez charger des images ou des fichiers Flash SWF dans la liste d’affichage d’une fenêtre native à l’aide de la classe flash.display.Loader : package { import import import import
//newWindow is a NativeWindow instance var htmlView:HTMLLoader = new HTMLLoader(); htmlView.width = 300; htmlView.height = 500; //set the stage so display objects are added to the top-left and not scaled newWindow.stage.align = "TL"; newWindow.stage.scaleMode = "noScale"; newWindow.stage.addChild( htmlView ); //urlString is the URL of the HTML page to load htmlView.load( new URLRequest(urlString) ); Par ailleurs, un contenu SWF ou PDF ne s’affiche pas si le contrôle HTMLLoader est mis à l’échelle ou pivoté ou si sa propriété alpha est définie sur une valeur autre que 1.0. Incrustation du contenu SWF sur une fenêtre HTML Etant donné que les fenêtres HTML sont contenues dans une occurrence de NativeWindow, vous pouvez ajouter des objets d’affichage Flash au-dessus et en dessous du calque HTML dans la liste d’affichage. Pour ajouter un objet d’affichage au-dessus du calque HTML, utilisez la méthode addChild() de la propriété window.nativeWindow.stage. La méthode addChild() ajoute le contenu superposé au-dessus du contenu existant dans la fenêtre. Pour ajouter un objet d’affichage en dessous du calque HTML, utilisez la méthode addChildAt() de la propriété window.nativeWindow.stage, en transmettant une valeur de zéro au paramètre index. Le fait de placer un objet à
« Programmation de l’affichage » à la page 156 du Guide du développeur d’ActionScript 3.0.
Adobe AIR 1.0 et les versions ultérieures L’exemple suivant illustre la méthode de création d’une fenêtre native : Utilisez les propriétés et les méthodes de la classe NativeWindow pour gérer l’aspect, le comportement et le cycle de vie des fenêtres du poste de travail. Remarque : si vous faites appel à la structure Flex, il est généralement préférable de gérer le comportement d’une fenêtre à l’aide des classes framework. Vous pouvez accéder à la plupart des propriétés et méthodes NativeWindow par le biais des classes mx:WindowedApplication et mx:Window.
Adobe AIR 1.0 et les versions ultérieures Pour manipuler une fenêtre, vous devez tout d’abord obtenir l’occurrence de la fenêtre. Vous pouvez obtenir une occurrence de fenêtre à partir de l’un des emplacements suivants :
Les objets Flex mx:WindowedApplication et mx:Window étant des objets d’affichage, vous pouvez aisément référencer la fenêtre d’application dans un fichier MXML à l’aide de la propriété stage, comme suit : <?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" applicationComplete="init();"> <mx:Script> Activation, affichage et masquage des fenêtres Adobe AIR 1.0 et les versions ultérieures Pour activer une fenêtre, appelez la méthode NativeWindow activate(). Lorsque vous activez une fenêtre, celle-ci s’affiche au premier plan, la souris et le clavier reçoivent le focus et, le cas échéant, il est possible de rendre visible la fenêtre en la restaurant ou en définissant la propriété visible sur true. L’activation d’une fenêtre ne modifie pas l’ordre des autres fenêtres dans l’application. Lorsque vous appelez la méthode activate(), la fenêtre distribue un événement activate. Pour afficher une fenêtre masquée sans l’activer, définissez la propriété visible sur true. Cette action amène la fenêtre au premier plan, mais ne lui donne pas le focus. Pour masquer une fenêtre, définissez sa propriété visible sur false. Le masquage d’une fenêtre supprime l’affichage de la fenêtre et des icônes de la barre des tâches associées et, sous Mac OS X, l’entrée dans le menu Fenêtre.
Modification de l’ordre d’affichage des fenêtres Adobe AIR 1.0 et les versions ultérieures AIR propose plusieurs méthodes pour modifier directement l’ordre d’affichage des fenêtres. Vous pouvez placer une fenêtre au premier plan ou à l’arrière-plan ; vous pouvez en outre placer une fenêtre sur ou sous une autre fenêtre. L’utilisateur peut simultanément réorganiser les fenêtres en les activant. Il est possible de maintenir une fenêtre au premier plan en définissant sa propriété alwaysInFront sur true. Si ce même paramètre est défini dans plusieurs fenêtres, l’ordre d’affichage est à nouveau déterminé au sein des ces fenêtres ; toutefois, ces fenêtres sont toujours placées au-dessus des fenêtres dont la propriété alwaysInFront est définie sur false. Les fenêtres du groupe de premier niveau sont toujours affichées devant les fenêtres d’autres applications, même si l’application AIR n’est pas active. Etant donné que ce comportement peut perturber les utilisateurs, définissez la propriété alwaysInFront sur true uniquement lorsque cela est nécessaire. Exemples de cas dans lesquels cet emploi est justifié :
Remarque : AIR n’impose pas l’utilisation correcte de la propriété alwaysInFront. Néanmoins, si votre application interrompt le flux de travail d’un utilisateur, il est probable qu’elle termine dans la corbeille de cet utilisateur. Si une fenêtre est propriétaire d’autres fenêtres, celles-ci s’affichent devant elle dans un ordre déterminé. Si vous appelez orderToFront() ou définissez alwaysInFront sur true pour une fenêtre propriétaire d’autres fenêtres, l’ordre d’affichage de ces dernières et celui de la fenêtre propriétaire est modifié devant d’autres fenêtres, mais elles continuent à s’afficher devant la fenêtre propriétaire. Appeler les méthodes de classement pour des fenêtres qui appartiennent à une autre fenêtre fonctionne normalement si elles appartiennent toutes à un même propriétaire, mais risque également de modifier l’ordre d’affichage du groupe entier de fenêtres. Ainsi, si vous appelez orderToFront() pour une fenêtre appartenant à une autre fenêtre, la fenêtre, son propriétaire et toute fenêtre appartenant éventuellement au même propriétaire sont affichées devant les autres fenêtres. La classe NativeWindow fournit les propriétés et les méthodes suivantes pour définir l’ordre d’affichage d’une fenêtre par rapport à d’autres fenêtres :
Le paramètre alwaysInFront n’affecte pas les fenêtres qui appartiennent à une autre fenêtre.
Dans le système d’exploitation Linux, les différents gestionnaires de fenêtres imposent des règles différentes quant à l’ordre d’affichage des fenêtres :
• Dans certains gestionnaires de fenêtres, une fenêtre plein écran dont la propriété alwaysInFront est définie sur true s’affiche toujours devant les autres fenêtres dont la propriété alwaysInFront est également définie sur true.
Adobe AIR 1.0 et les versions ultérieures Pour fermer une fenêtre, utilisez la méthode NativeWindow.close(). La fermeture d’une fenêtre décharge le contenu de la fenêtre, mais si les autres objets possèdent des références à ce contenu, les objets de contenu ne sont pas détruits. La méthode NativeWindow.close() s’exécute de façon asynchrone, et l’application contenue dans la fenêtre continue de fonctionner lors de la fermeture. La méthode de fermeture distribue un événement close lorsque l’opération de fermeture est terminée. Techniquement, l’objet NativeWindow est toujours valide, mais l’accès à la plupart des propriétés et des méthodes sur une fenêtre fermée génère un erreur IllegalOperationError. Vous ne pouvez pas ouvrir à nouveau une fenêtre fermée. Vérifiez la propriété closed d’une fenêtre pour vous assurer que la fenêtre a été fermée. Pour simplement masquer une fenêtre, définissez la propriété NativeWindow sur false. Si la propriété Nativeapplication.autoExit est définie sur true (valeur par défaut), l’application se ferme lors de la fermeture de sa dernière fenêtre. La fermeture d’une fenêtre qui possède d’autres fenêtres entraîne la fermeture de ces dernières. Etant donné que les fenêtres qui appartiennent à la fenêtre propriétaire ne distribuent pas d’événement closing, il est impossible d’interdire leur fermeture. Un événement close est distribué.
Lorsqu’une fenêtre utilise le chrome système, l’interaction de l’utilisateur avec la fenêtre peut être annulée en écoutant les événements appropriés et en annulant leur comportement par défaut. Par exemple, lorsqu’un utilisateur clique sur le bouton de fermeture du chrome système, l’événement closing est distribué. Si l’un des écouteurs enregistrés appelle la méthode preventDefault() de l’événement, la fenêtre ne se ferme pas. Si une fenêtre n’utilise pas le chrome système, les événements de notification des modifications désirées ne sont pas automatiquement distribués avant que la modification ait lieu. Donc, si vous appelez les méthodes qui permettent de fermer une fenêtre, d’en modifier l’état ou d’en définir les propriétés de limite, la modification ne peut pas être annulée. Pour notifier les composants dans votre application avant d’effectuer une modification, votre logique d’application peut distribuer l’événement de notification adéquat à l’aide de la méthode dispatchEvent() de la fenêtre. Par exemple, la logique suivante implémente un gestionnaire d’événement pouvant être annulé pour le bouton de fermeture d’une fenêtre : public function onCloseCommand(event:MouseEvent):void{ var closingEvent:Event = new Event(Event.CLOSING,true,true); dispatchEvent(closing); if(!closingEvent.isDefaultPrevented()){ win.close(); } }
écouteur. Toutefois, elle peut également renvoyer false pour d’autres raisons ; par conséquent, il convient d’utiliser explicitement la méthode isDefaultPrevented() afin de vérifier si la modification doit ou non être annulée.
Adobe AIR 1.0 et les versions ultérieures Pour agrandir la fenêtre, utilisez la méthode maximize() de la classe NativeWindow. myWindow.maximize();
Remarque : le comportement résultant de l’agrandissement d’une fenêtre AIR est différent du comportement standard de Mac OS X. Plutôt que de basculer entre la taille « standard » définie par l’application et la dernière taille définie par l’utilisateur, les fenêtres AIR basculent entre la dernière taille définie par l’application ou l’utilisateur et la totalité de la zone utilisable de l’écran.
• Si une taille maximale est définie pour la fenêtre, certains gestionnaires n’autorisent pas l’agrandissement de la fenêtre. D’autres gestionnaires de fenêtres définissent l’état d’affichage sur l’état maximal, mais ne redimensionnent pas la fenêtre. Dans tous les cas, aucun événement de modification d’état d’affichage n’est distribué.
Remarque : sous Linux, les propriétés des fenêtres sont modifiées de façon asynchrone. Si vous modifiez l’état d’affichage sur une ligne de votre programme et que vous lisez la valeur à la ligne suivante, la modification n’est pas répercutée. Sur toutes les plates-formes, l’objet NativeWindow distribue l’événement displayStateChange lors de la modification de l’état d’affichage. Si vous devez exécuter une action basée sur le nouvel état de la fenêtre, faites systématiquement appel à un gestionnaire d’événement displayStateChange. Pour plus d’informations, voir « Ecoute des événements d’une fenêtre » à la page 951.
Adobe AIR 1.0 et les versions ultérieures La brève application MXML suivante illustre les méthodes maximize(), minimize(), restore() et close() de la classe Window :
Remarque : pour redimensionner ou déplacer une fenêtre, vous devez tout d’abord obtenir une référence à l’occurrence de NativeWindow. Pour plus d’informations sur la méthode d’obtention d’une référence de fenêtre, voir la section « Obtention d’une occurrence de NativeWindow » à la page 940. Redimensionnement d’une fenêtre Pour que l’utilisateur puisse interagir avec la taille d’une fenêtre, utilisez la méthode startResize() de la classe NativeWindow. Lorsque cette méthode est appelée depuis un événement mouseDown, l’opération de redimensionnement est effectuée par la souris et se termine lorsque le système d’exploitation reçoit un événement mouseUp. Lors de l’appel de la méthode startResize(), vous transmettez un argument qui indique le bord ou le coin à partir duquel la fenêtre doit être redimensionnée. Pour définir la taille de la fenêtre par programmation, définissez les propriétés width, height ou bounds de la fenêtre sur les dimensions désirées. Lorsque vous définissez les limites, la taille et la position de la fenêtre peuvent changer simultanément. Toutefois, l’ordre de ces changements n’est pas garanti. Certains gestionnaires de fenêtres Linux ne permettent pas aux fenêtres de dépasser les limites de l’écran. Dans ce cas, la taille finale de la fenêtre peut être limitée du fait de l’ordre dans lequel les propriétés sont définies, même si l’impact des modifications aurait autrement résulté en une fenêtre valide. Par exemple, si vous modifiez à la fois la hauteur et la position y d’une fenêtre à proximité du bas de l’écran, la modification en pleine hauteur peut ne pas survenir lorsque la hauteur est modifiée avant la position y.
Le mode d’échelle de la scène indique le comportement de la scène de la fenêtre et de son contenu lorsqu’une fenêtre est redimensionnée. N’oubliez pas que les modes d’échelle de la scène sont conçus pour les situations où l’application ne contrôle pas la taille ou le format de son espace d’affichage (notamment dans le cas d’un navigateur Web). En règle générale, vous obtenez les meilleurs résultats en définissant la propriété scaleMode de la scène sur StageScaleMode.NO_SCALE. Pour mettre à l’échelle le contenu d’une fenêtre, vous pouvez toujours définir les paramètres scaleX et scaleY du contenu lors des modifications des limites de la fenêtre. Déplacement d’une fenêtre Pour déplacer une fenêtre sans la redimensionner, utilisez la méthode startMove() de la classe NativeWindow. A l’instar de la méthode startResize(), lorsque la méthode startMove() est appelée à partir d’un événement mouseDown, le déplacement est effectué avec la souris et se termine lorsque le système d’exploitation reçoit un événement mouseUp. Pour plus d’informations sur les méthodes startResize() et startMove(), voir le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash. Pour déplacer une fenêtre par programmation, définissez les propriétés x, y ou bounds de la fenêtre sur la position requise. Lorsque vous définissez les limites, la taille et la position de la fenêtre peuvent changer simultanément. Remarque : sous Linux, les propriétés des fenêtres sont modifiées de façon asynchrone. Si vous déplacez une fenêtre sur une ligne de votre programme et que vous lisez la position à la ligne suivante, la modification n’est pas répercutée. Sur toutes les plates-formes, l’objet NativeWindow distribue l’événement move lors du repositionnement de la fenêtre. Si vous devez exécuter une action basée sur la nouvelle position de la fenêtre, faites systématiquement appel à un gestionnaire d’événement move. Pour plus d’informations, voir « Ecoute des événements d’une fenêtre » à la page 951.
Adobe AIR 1.0 et les versions ultérieures L’exemple suivant montre comment lancer les opérations de redimensionnement et de déplacement sur une fenêtre :
Pour écouter les événements distribués par une fenêtre, enregistrez un écouteur avec l’occurrence de la fenêtre. Par exemple, pour écouter un événement closing, enregistrez un écouteur avec la fenêtre, comme suit : myWindow.addEventListener(Event.CLOSING, onClosingEvent);
La plupart des événements de fenêtre sont associés à deux messages. Le premier message signale l’imminence d’une modification au niveau de la fenêtre (modification pouvant être annulée) ; le second message indique que la modification a été effectuée. Par exemple, lorsqu’un utilisateur clique sur le bouton de fermeture d’une fenêtre, le message de l’événement closing est distribué. Si aucun écouteur n’annule l’événement, la fenêtre se ferme et l’événement close est distribué à l’un des écouteurs. En règle générale, les événements d’avertissement, tels que closing, ne sont distribués que lorsque le chrome système a été utilisé pour déclencher un événement. L’appel de la méthode close(), par exemple, ne distribue pas automatiquement l’événement closing ; seul l’événement close est distribué. Vous pouvez toutefois créer un événement closing et le distribuer à l’aide de la méthode dispatchEvent() de la fenêtre. Les événements de fenêtre qui distribuent un objet Event sont les suivants : Evénement
Les événements de fenêtre qui distribuent un objet NativeWindowDisplayStateEvent sont les suivants :
Dans certains gestionnaires de fenêtres Linux, aucun événement de modification de l’état d’affichage n’est distribué lors de l’agrandissement d’une fenêtre possédant un paramètre de taille maximale. (La fenêtre est définie sur l’état d’affichage maximal, mais n’est pas redimensionnée.)
Adobe AIR 1.0 et les versions ultérieures La définition de la propriété displayState de la scène sur StageDisplayState.FULL_SCREEN_INTERACTIVE met la fenêtre en mode plein écran et la saisie clavier is est autorisée dans ce mode. (Pour le contenu SWF s’exécutant dans un navigateur, la saisie clavier n’est pas autorisée). Pour quitter le mode plein écran, l’utilisateur doit appuyer sur la touche Echap. Remarque : certains gestionnaires de fenêtres Linux ne modifient pas les dimensions de la fenêtre pour remplir l’écran si une taille maximale est définie pour celle-ci (mais suppriment le chrome système de la fenêtre). Par exemple, le code Flex suivant définit une application AIR simple qui configure un terminal d’écran complet : <?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical" applicationComplete="init()" backgroundColor="0x003030" focusRect="false"> <mx:Script> L’interface de programmation de l’écran contient une seule classe, Screen, qui permet à des membres statiques de lire des informations système sur les écrans et à des membres d’occurrences de décrire un écran particulier. Plusieurs écrans peuvent être reliés à un système d’ordinateurs, ce qui peut donner lieu à un espace virtuel qui contient plusieurs écrans d’ordinateur. La classe Screen d’AIR fournit des informations sur les écrans, leur organisation relative et leur espace utilisable. Si plusieurs moniteurs mappent sur le même écran, seul un écran existe. Si la taille d’un écran est plus grande que la zone d’affichage du moniteur, il n’y a pas moyen de savoir quelle partie de l’écran est actuellement visible. Un écran représente une zone d’affichage indépendante de l’ordinateur. Les écrans sont décrits comme des rectangles au sein d’un ordinateur de bureau virtuel. Le coin supérieur gauche de l’écran désigné comme zone d’affichage principale constitue l’origine du système de coordonnées de l’ordinateur virtuel. Toutes les valeurs utilisées dans la description d’un écran sont exprimées en pixels.
Pour plus d’informations sur la classe, les méthodes, les propriétés et les événements de l’interface de programmation d’écran, voir Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash.
Adobe AIR 1.0 et les versions ultérieures Vous pouvez dénombrer les écrans d’un ordinateur de bureau virtuel avec les méthodes et propriétés suivantes : Méthode ou propriété
N’enregistrez pas les valeurs renvoyées par les méthodes et propriétés de la classe Screen. L’utilisateur ou le système d’exploitation peuvent changer les écrans disponibles et leur organisation en tout temps. L’exemple suivant utilise l’interface de programmation des écrans pour déplacer une fenêtre entre plusieurs écrans en réponse à la pression sur les touches de direction. Pour déplacer la fenêtre sur l’écran suivant, l’exemple lit le tableau screens et le trie verticalement ou horizontalement, suivant la touche de direction sur laquelle on a appuyé. Le code parcourt le tableau trié en comparant chaque écran aux coordonnées de l’écran actif. Pour identifier l’écran actif de la fenêtre, l’exemple appelle Screen.getScreensForRectangle() en le transmettant dans les limites de la fenêtre.
Les stratégies d’utilisation des méthodes et propriétés de la classe flash.printing.PrintJob sont passées en revue ci-après. Elles permettent de créer une tâche d’impression, de lire les paramètres d’impression d’un utilisateur et d’ajuster une tâche d’impression en fonction des informations renvoyées par un moteur d’exécution de Flash et le système d’exploitation de l’utilisateur.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Dans ActionScript 3.0, vous utilisez la classe PrintJob pour créer des instantanés de contenu d’affichage à convertir en représentation encre-et-papier dans une impression. Dans certains cas, définir le contenu à imprimer revient à le définir pour un affichage à l’écran—vous positionnez et dimensionnez des éléments pour créer la mise en forme souhaitée. Néanmoins, l’impression a des caractéristiques qui la différencient de la mise en forme à l’écran. Par exemple, les imprimantes utilisent une résolution différente des écrans d’ordinateur. Le contenu d’un écran d’ordinateur est dynamique et peut changer, alors que le contenu imprimé est statique. Lorsque vous planifiez une impression, tenez compte des contraintes de taille de page fixe et de la possibilité d’imprimer plusieurs pages. Aussi évidentes que puissent paraître ces différences, il est important de les garder à l’esprit lors de la configuration de l’impression avec ActionScript. Une impression précise repose sur la combinaison des valeurs stipulées par vous et des caractéristiques de l’imprimante de l’utilisateur. Les propriétés de la classe PrintJob permettent de déterminer les caractéristiques importantes de l’imprimante de l’utilisateur. Concepts importants et terminologie La liste de référence suivante contient des termes importants relatifs à l’impression : Spouleur Partie du système d’exploitation ou du logiciel du pilote d’imprimante qui effectue le suivi des pages en attente d’impression et les envoie à l’imprimante dès qu’elle est disponible. Orientation de page Rotation du contenu imprimé par rapport au papier (horizontale - paysage ou verticale -
Tâche d’impression Page ou jeu de pages constituant une seule impression. Player ou AIR, vous utilisez quatre instructions à la suite :
Utilisation des exceptions et des renvois Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Avant d’appeler addPage() et send(), vérifiez que la méthode PrintJob.start() renvoie la valeur true, au cas où l’utilisateur aurait annulé la tâche d’impression. Une manière simple de vérifier si ces méthodes ont été annulées avant de poursuivre consiste à les intégrer à une instruction if, comme suit : if (myPrintJob.start()) { // addPage() and send() statements here } Utilisation des propriétés de page Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lorsque l’utilisateur clique sur OK dans la boîte de dialogue d’impression et que PrintJob.start() renvoie true, vous pouvez accéder aux propriétés définies par les paramètres de l’imprimante. Il s’agit notamment de la largeur et de la hauteur du papier (pageHeight et pageWidth) et de l’orientation du contenu sur la feuille. Puisque ces paramètres d’impression ne sont pas contrôlés par le moteur d’exécution Flash, il est impossible de les modifier. Vous pouvez en revanche les utiliser pour faire correspondre le contenu à envoyer à l’imprimante aux paramètres en cours. Pour plus d’informations, voir « Définition de la taille, de l’échelle et de l’orientation » à la page 963.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous avez la possibilité de définir manuellement la tâche d’impression de manière à transmettre chaque page sous forme d’image vectorielle ou bitmap. Dans certains cas, l’impression vectorielle produit un fichier de file d’attente plus réduit et une image de meilleure qualité que l’impression bitmap. Toutefois, si le contenu inclut une image bitmap et que vous souhaitez préserver la transparence alpha ou tout autre effet de couleur, imprimez la page en tant qu’image bitmap. En outre, une imprimante non-PostScript convertit automatiquement les graphiques vectoriels en images bitmap.
Pour AIR 2 et les versions ultérieures, faites appel à la propriété printMethod de l’objet PrintJobOptions pour spécifier la méthode d’impression. Cette propriété gère trois valeurs, qui sont définies en tant que constantes dans la classe PrintMethod :
Toutefois, si une image en filigrane avec transparence Alpha est superposée au texte, l’impression bitmap est choisie pour conserver la transparence.
Contrairement aux versions précédentes, ActionScript 3.0 ne limite pas un objet PrintJob à une image unique. Cependant, comme le système d’exploitation indique l’état de l’impression après que l’utilisateur a cliqué sur le bouton OK dans la boîte de dialogue d’impression, appelez PrintJob.addPage() et PrintJob.send() dès que possible pour envoyer les pages au spouleur. Si l’accès à l’image contenant l’appel PrintJob.send() est soumis à un délai, le processus d’impression est également retardé. Dans ActionScript 3.0, le délai de script est de 15 secondes. Par conséquent, l’intervalle entre chaque instruction essentielle de la séquence de tâche d’impression ne peut pas dépasser 15 secondes. En d’autres termes, la limite de 15 secondes concerne les intervalles suivants :
• Entre PrintJob.addPage() et l’instruction suivante PrintJob.addPage() • Entre la dernière instruction
PrintJob entraîne le renvoi d’une exception d’exécution par Flash Player ou AIR.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La section « Impression d’une page » à la page 959 décrit en détail les étapes d’une tâche d’impression de base, dans laquelle la sortie reproduit directement le sprite spécifié, selon sa taille d’affichage et sa position à l’écran. Néanmoins, les imprimantes utilisent différentes résolutions d’impression et certains de leurs paramètres peuvent altérer l’aspect du sprite imprimé. Les moteurs d’exécution Flash peuvent lire les paramètres d’impression du système d’exploitation, mais notez que ces propriétés sont accessibles en lecture seule. En d’autres termes, bien que vous puissiez réagir à leur valeur, il est possible de les définir. Par exemple, il est possible de déterminer le paramètre de format de page de l’imprimante et d’ajuster votre contenu en fonction. Vous pouvez de même identifier les paramètres de marge de l’imprimante ainsi que l’orientation des pages. Pour répondre aux paramètres de l’imprimante, spécifiez une zone d’impression, effectuez un ajustement pour tenir compte de la différence entre la résolution de l’écran et la mesure de points de l’imprimante, ou faites correspondre le contenu aux paramètres de taille et d’orientation de l’imprimante de l’utilisateur.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La méthode PrintJob.addPage() vous permet de spécifier la partie du sprite que vous souhaitez imprimer. Le deuxième paramètre, printArea prend la forme d’un objet Rectangle. Vous pouvez fournir la valeur de ce paramètre de trois manières :
Comparaison entre les points et les pixels Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La largeur et la hauteur d’un rectangle sont exprimées en pixels. Une imprimante utilise les points en tant qu’unités de mesure. Les points ont une taille physique fixe (1/72e de pouce), mais la taille d’un pixel à l’écran varie selon la résolution de ce dernier. De ce fait, le taux de conversion entre les pixels et les points dépend de la configuration de l’imprimante et du redimensionnement éventuel du sprite. Un sprite non redimensionné d’une largeur de 72 pixels mesure un pouce (2,54 cm) de large lorsqu’il est imprimé, sachant qu’un point correspond à un pixel quelle que soit la résolution de l’écran.
Si vous souhaitez redimensionner un objet Sprite avant de l’imprimer, définissez les propriétés de redimensionnement (voir « Manipulation de la taille et de l’échelle des objets » à la page 186) avant d’appeler la méthode PrintJob.addPage(), puis rétablissez leurs valeurs d’origine après l’impression. L’échelle d’un objet Sprite ne dépend pas de la propriété printArea. En d’autres termes, si vous spécifiez une zone d’impression de 50 pixels par 50 pixels, 2 500 pixels sont imprimés. Si vous redimensionnez l’objet Sprite, les 2 500 pixels sont imprimés, mais l’objet est imprimé à l’échelle retenue. A titre d’exemple, voir « Exemple d’impression : mise à l’échelle, recadrage et ajustement » à la page 969.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Flash Player et AIR étant capables de détecter les paramètres d’orientation, vous pouvez insérer dans votre code ActionScript une logique permettant d’ajuster la taille du contenu ou son orientation en fonction des paramètres de l’imprimante, comme illustré dans l’exemple ci-après. if (myPrintJob.orientation == PrintJobOrientation.LANDSCAPE) { mySprite.rotation = 90; }
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Par l’utilisation d’une stratégie semblable à la gestion des paramètres d’orientation de l’imprimante, vous pouvez lire les paramètres de hauteur et de largeur de page, puis en tenir compte en intégrant une logique dans une instruction if. Le code suivant illustre ce cas de figure : if (mySprite.height > myPrintJob.pageHeight) { mySprite.scaleY = .75; }
L’utilisateur peut définir les étendues de pages, le format du papier, l’orientation et la mise à l’échelle avant de lancer l’impression.
Le nouveau flux de travaux d’impression se compose des étapes suivantes :
Par défaut, elle est définie sur le nom de l’imprimante par défaut. La propriété printer est définie sur null si aucune imprimante n’est disponible ou si le système ne prend pas en charge l’impression. Pour changer d’imprimante, commencez par obtenir la liste des imprimantes disponibles par le biais de la propriété printers. Cette propriété est un objet Vector dont les éléments String correspondent aux noms d’imprimantes disponibles. Définissez la propriété printer sur l’une de ces valeurs String pour activer l’imprimante correspondante. Il est impossible de modifier la propriété printer d’une tâche d’impression active. Toute tentative de modification de cette propriété après qu’un appel de start() ou start2() a abouti ou avant l’envoi ou l’arrêt de la tâche d’impression échoue. Exemple de définition de la propriété :
Si vous devez imprimer plusieurs pages de contenu, vous pouvez associer chaque page à un sprite différent (dans le cas présent, sheet1 et sheet2). Utilisez ensuite PrintJob.addPage() pour chaque sprite. Le code suivant illustre cette technique :
Dernière mise à jour le 27/4/2013
événement update est un objet GeolocationEvent.
Pour utiliser le capteur de géolocalisation, instanciez un objet Geolocation et enregistrez-vous pour recevoir les événements update qu’il distribue. Un événement update est un objet GeolocationEvent. Il possède huit propriétés :
L’utilisateur peut interdire à une application d’accéder aux données de géolocalisation. L’iPhone avertit par exemple l’utilisateur lorsqu’une application tente d’obtenir des données de géolocalisation. En réponse à l’invite, l’utilisateur peut refuser à l’application tout accès aux données de géolocalisation. L’objet Geolocation distribue un événement status lorsque l’utilisateur refuse l’accès aux données de géolocalisation. Il possède également une propriété muted, définie sur true lorsque le capteur de géolocalisation n’est pas disponible. L’objet Geolocation distribue un événement status lorsque la propriété muted change. Le code suivant indique comment détecter que les données de géolocalisation ne sont pas disponibles :
Vérification de la prise en charge de la géolocalisation La propriété Geolocation.isSupported permet de vérifier si l’environnement d’exécution prend en charge cette fonction : if (Geolocation.isSupported) { // Set up geolocation event listeners and code. } Certains modèles d’iPhone ne sont pas équipés d’une unité GPS. Ces modèles font appel à d’autres techniques, telles que la localisation par triangulation des téléphones portables, pour obtenir les données de géolocalisation. Pour ces modèles, ou sur tout iPhone dont l’unité GPS est désactivée, un objet Geolocation risque de ne distribuer qu’un ou deux événements update initiaux.
Les termes globalisation et internationalisation sont parfois considérés comme interchangeables. La plupart des définitions de ces termes indiquent toutefois que globalisation se réfère à une combinaison de processus commerciaux et d’ingénierie, tandis qu’internationalisation relève exclusivement de l’ingénierie. Quelques termes importants sont définis ci-dessous : Globalisation Large éventail de processus commerciaux et d’ingénierie destinés à assurer la préparation et le lancement globaux de produits et d’actions d’entreprise. La globalisation rassemble des activités d’ingénierie telles que l’internationalisation, la localisation et la différentiation culturelle, ainsi que des activités commerciales telles que la gestion de produits, la planification financière, le marketing et les tâches d’ordre juridiques. La globalisation est parfois abrégée sous la forme G11n (G, puis 11 autres lettres, puis la lettre n). « C’est aux entreprises qu’incombe la globalisation. » Internationalisation Processus d’ingénierie destiné à « dé-régionaliser » un produit pour assurer la prise en charge de
Localisation Processus consistant à adapter un produit ou un service à une langue et une culture données, ainsi qu’à
Différentiation culturelle Processus relevant de l’ingénierie destiné à développer ou adapter des fonctionnalités
Internationalisation des applications
Jeu de caractères Caractères utilisés par une langue ou un groupe de langues. Un jeu de caractères comprend les caractères nationaux, les caractères spéciaux (tels les signes de ponctuation et les symboles mathématiques), les chiffres et les caractères de contrôle informatiques. Classement Tri du texte dans un ordre adapté à des paramètres régionaux déterminés. Paramètres régionaux Valeur qui représente la langue et les conventions culturelles en vigueur dans une région géographique, politique ou culturelle (soit, dans de nombreux cas, un pays unique). A cette valeur correspond un identifiant de paramètres régionaux (ID de paramètres régionaux) unique. L’ID de paramètres régionaux permet de rechercher un jeu de données régionales qui assure une prise en charge régionale appropriée. Cette prise en charge s’applique aux unités de mesure, à l’analyse et au formatage des nombres et des dates, etc. Regroupement de ressources Jeu stocké d’éléments propres aux paramètres régionaux utilisés par une application. Un regroupement de ressources contient généralement tous les éléments de texte de l’interface utilisateur de l’application. Au sein du regroupement, ces éléments sont traduits dans la langue correspondant aux paramètres régionaux. Le regroupement de ressources comporte parfois d’autres paramètres qui modifient la mise en forme ou le comportement de l’interface utilisateur pour des paramètres régionaux déterminés. Il est ainsi susceptible de contenir d’autres types de médias ou des références à ces derniers, propres aux paramètres régionaux.
Flash Player 10.1 et les versions ultérieures, Adobe AIR 2.0 et les versions ultérieures Le package flash.globalization exploite les fonctionnalités de prise en charge culturelle du système d’exploitation sousjacent. Il simplifie la programmation d’applications conformes aux conventions culturelles de chaque utilisateur. Parmi les principales classes du package figurent :
• La classe CurrencyFormatter, qui formate les nombres convertis en chaînes de montant de devise et analyse les symboles et montants de devise extraits de chaînes d’entrée.
• La classe LocaleID, qui extrait les informations relatives à des paramètres régionaux donnés. • La classe NumberFormatter, qui formate et analyse les valeurs numériques. • La classe StringTools, qui gère la conversion de la casse des chaînes gérées par les paramètres régionaux.
Le package flash.globalization ne gère pas la localisation des ressources. Vous pouvez toutefois utiliser l’ID de paramètres régionaux flash.globalization en tant que principale valeur d’extraction des ressources localisées par le biais d’autres techniques. Il est ainsi possible de localiser les ressources d’une application créées dans Flex à l’aide des classes ResourceManager et ResourceBundle. Pour plus d’informations, voir Localisation d’applications Flex. Adobe AIR 1.1 contient également quelques fonctions destinées à faciliter la localisation des applications AIR, comme indiqué à la section « Localisation d’applications AIR » à la page 997.
4 Formatez et affichez les informations à l’aide des paramètres régionaux en vigueur.
• prendre en charge d’autres systèmes d’écriture à l’aide de FTE (Flash Text Engine) ; • vérifier la gestion appropriée des éditeurs de méthode d’entrée.
Les classes de service flash.globalization adoptent toutes une approche similaire pour identifier les erreurs. En cas de non-disponibilité des paramètres régionaux requis, elles ont également toutes recours aux paramètres régionaux pris en charge par le système d’exploitation de l’utilisateur. L’exemple suivant indique comment rechercher les erreurs et paramètres de substitution lors de l’instanciation de classes de service. Chaque classe de service possède une propriété lastOperationStatus, qui indique si la dernière méthode utilisée a déclenché des messages d’erreur ou des avertissements. var nf:NumberFormatter = new NumberFormatter("de-DE"); if(nf.lastOperationStatus != LastOperationStatus.NO_ERROR) { if(nf.lastOperationStatus == LastOperationStatus.USING_FALLBACK_WARNING) { // perform fallback logic here, if needed trace("Warning - Fallback locale ID: " + nf.actualLocaleIDName); Flash Player 10.1 et les versions ultérieures, Adobe AIR 2.0 et les versions ultérieures Les paramètres régionaux identifient une combinaison donnée de conventions linguistiques et culturelles en vigueur dans un pays ou une région. Un identifiant de paramètres régionaux peut être géré en toute sécurité en tant que chaîne. Vous disposez toutefois de la classe LocaleID pour obtenir d’autres informations relatives aux paramètres régionaux. Procédez comme suit pour créer un objet LocaleID : var locale:LocaleID = new LocaleID("es-MX");
Les valeurs extraites de ces méthodes et propriétés contiennent parfois des informations complémentaires sur les paramètres régionaux qu’il est impossible de récupérer directement de l’identifiant de paramètres régionaux. Lorsqu’une application crée un service qui gère les paramètres régionaux, telle une fonctionnalité de formatage de dates, elle doit stipuler les paramètres régionaux prévus. Etant donné que la liste des paramètres régionaux pris en charge varie d’un système d’exploitation à l’autre, il arrive parfois que les paramètres régionaux requis ne soient pas disponibles. Flash Player essaie d’abord de trouver le code de langue des paramètres régionaux requis. Il tente ensuite de préciser les paramètres régionaux en trouvant un système d’écriture (script) et une région correspondants. Exemple : var loc:LocaleID = new LocaleID("es"); trace(loc.getLanguage()); // es trace(loc.getScript()); // Latn
Vous disposez de plusieurs méthodes pour définir les paramètres régionaux actifs d’une application :
1 Récupérez la liste des paramètres régionaux ou langues préférés de l’utilisateur à partir d’un profil utilisateur, des
2 Identifiez les paramètres régionaux pris en charge par l’application et sélectionnez la valeur la plus adaptée par
3 Autorisez l’utilisateur à modifier les paramètres régionaux par défaut s’ils ne lui conviennent pas.
La classe fl.lang.Locale permet de remplacer les chaînes de texte basées sur des paramètres régionaux en utilisant les regroupements de ressources qui contiennent les valeurs de chaîne. Cette classe ne prend toutefois pas en charge les autres fonctions d’internationalisation telles que le formatage, le tri et la mise en correspondance des nombres, des devises ou de la date. Elle est par ailleurs réservée à Flash Professional. Vous pouvez également récupérer le code de langue actif associé au système d’exploitation à l’aide de la propriété flash.system.Capabilities.language. Cette propriété n’extrait toutefois que le code de langue ISO 639-1 à deux
Dans AIR 1.5, vous disposez de la propriété flash.system.Capabilities.languages. Cette propriété génère un tableau contenant les langues d’interface privilégiées par l’utilisateur. Elle n’est donc pas sujette aux restrictions de Capabilities.language.
Flash Player 10.1 et les versions ultérieures, Adobe AIR 2.0 et les versions ultérieures Le format d’affichage des valeurs numériques varie considérablement d’une région à l’autre. Le nombre 123456,78 est par exemple formaté comme suit selon les paramètres régionaux en vigueur : Paramètres régionaux
La classe NumberFormatter formate les valeurs numériques (de type int, uint ou Number) en fonction des conventions de paramètres régionaux donnés. L’exemple suivant illustre la façon la plus simple de formater un nombre en fonction des propriétés de formatage par défaut gérées par le système d’exploitation de l’utilisateur : var nf:NumberFormatter = new NumberFormatter(LocaleID.DEFAULT); trace(nf.formatNumber(-123456.789))
-123.456,789 Si vous souhaitez vous limiter au formatage d’un nombre en fonction de paramètres régionaux donnés, quels que soient les paramètres de l’utilisateur, définissez spécifiquement le nom des paramètres régionaux. Exemple : var nf:NumberFormatter = new NumberFormatter("de-CH"); trace(nf.formatNumber(-123456.789));
-123’456.789 La méthode formatNumber() traite la valeur Number comme un paramètre. La classe NumberFormatter gère également une méthode formatInt(), qui gère l’entrée int, et une méthode formatUint(), qui gère l’entrée uint. Pour contrôler explicitement la logique de formatage, définissez les propriétés de la classe NumberFormatter, comme illustré ci-dessous : var nf:NumberFormatter = new NumberFormatter("de-CH"); nf.negativeNumberFormat = 0; nf.fractionalDigits = 5; nf.trailingZeros = true; nf.decimalSeparator = ","; nf.useGrouping = false; trace(nf.formatNumber(-123456.789)); //(123456.78900)
• définit le séparateur décimal sur une virgule ; • indique à la fonctionnalité de formatage de ne pas utiliser de séparateur de milliers. Remarque : si certaines de ces propriétés sont modifiées, le format numérique résultant ne correspond plus au format préféré associé aux paramètres régionaux indiqués. Ne faites appel à certaines de ces propriétés que si la prise en charge des paramètres régionaux est superflue, comme dans les cas de figure suivants : si un aspect unique du format doit être contrôlé avec précision (le nombre de zéros à droite, par exemple) ou si l’utilisateur demande directement la modification (via le Panneau de configuration Windows, par exemple).
La classe NumberFormatter peut également extraire des valeurs numériques de chaînes conformes aux conventions de formatage stipulées par les paramètres régionaux. La méthode NumberFormatter.parseNumber() extrait une valeur numérique unique d’une chaîne. Exemple : var nf:NumberFormatter = new NumberFormatter( "en-US" ); var inputNumberString:String = "-1,234,567.890" var parsedNumber:Number = nf.parseNumber(inputNumberString); trace("Value:" + parsedNumber); // -1234567.89 trace("Status:" + nf.lastOperationStatus); // noError
Flash Player 10.1 et les versions ultérieures, Adobe AIR 2.0 et les versions ultérieures Les formats d’affichage des valeurs en devise varient tout autant que les formats numériques. La valeur 123456,78 $ est par exemple formatée comme suit selon les paramètres régionaux en vigueur : Paramètres régionaux
La classe CurrencyFormatter transforme les valeurs numériques en chaînes contenant des chaînes de devise et des nombres formatés, conformément aux conventions de paramètres régionaux donnés. Lorsque vous instanciez un nouvel objet CurrencyFormatter, il définit la devise sur la devise associée par défaut aux paramètres régionaux en vigueur. L’exemple suivant indique qu’un objet CurrencyFormatter créé à partir de paramètres régionaux allemands part du principe que les montants en devise sont exprimés en euros : var cf:CurrencyFormatter = new CurrencyFormatter( "de-DE" );
La méthode CurrencyFormatter.setCurrency() spécifie la chaîne et le symbole de devise exacts à utiliser. L’exemple suivant affiche les montants en devise en euros à l’intention des utilisateurs québécois : var cf:CurrencyFormatter = new CurrencyFormatter( "fr-CA" ); cf.setCurrency("EUR", "€");
Les codes ISO 4217 ne sont pas ambigus et ne nécessitent pas de localisation. Un grand nombre d’utilisateurs préfèrent toutefois les symboles de devise aux codes ISO. La classe CurrencyFormatter peut vous aider à décider du symbole utilisé par une chaîne en devise formatée : un symbole de devise ($ ou €, par exemple) ou une chaîne de devise ISO de trois caractères (USD ou EUR, par exemple). Ainsi, un montant exprimé en dollars canadiens pourrait être affiché sous la forme $200 à l’intention d’un utilisateur qui réside au Canada. Pour un utilisateur qui réside aux Etats-Unis, il pourrait par contre être affiché sous la forme CAD 200. La méthode formattingWithCurrencySymbolIsSafe() permet de déterminer si le symbole de devise d’un montant risque d’être ambigu ou incorrect en fonction des paramètres régionaux de l’utilisateur. L’exemple suivant affiche une valeur en euros dans un format adapté aux paramètres régionaux en-US. Selon les paramètres régionaux de l’utilisateur, la chaîne sortie contient soit le code de devise ISO, soit le symbole de devise. var cf:CurrencyFormatter = new CurrencyFormatter( "en-CA"); if (cf.formattingWithCurrencySymbolIsSafe("USD")) { trace(cf.format(1234567.89, true)); // $1,234,567.89 } else { cf.setCurrency("USD", "$"); trace(cf.format(1234567.89)); // USD1,234,567.89 Formatage des dates et heures Flash Player 10.1 et les versions ultérieures, Adobe AIR 2.0 et les versions ultérieures Le format d’affichage de la date et de l’heure varie également considérablement d’une région à l’autre. Voici par exemple comment le 2 janvier 1962 à 13:01 est affiché dans un format court en fonction de divers paramètres régionaux : Paramètres régionaux
Le formatage est régi par une chaîne modèle qui contient des séquences de lettres remplacées par des valeurs de date ou d’heure. Par exemple, dans le modèle « yyyy/MM », les caractères « yyyy » sont remplacés par une année à quatre chiffres, suivie du caractère « / » et d’un mois à deux chiffres. La méthode setDateTimePattern() permet de définir explicitement la chaîne modèle. Il est toutefois préférable d’activer la définition automatique du modèle en fonction des préférences du système d’exploitation et des paramètres régionaux de l’utilisateur. Cette stratégie contribue à assurer un résultat approprié d’un point de vue culturel. L’élément DateTimeFormatter peut représenter des dates et heures en trois styles standard (LONG, MEDIUM et SHORT) et faire appel à un modèle CUSTOM. Vous pouvez utiliser un style pour la date et un autre pour l’heure. Les modèles associés à chaque style varient sensiblement d’un système d’exploitation à l’autre.
De nombreuses applications font appel à des listes de noms de mois et de jour de la semaine dans les calendriers ou listes déroulantes affichés. La méthode DateTimeFormatter.getMonthNames() permet de récupérer une liste localisée de noms de mois. Le système d’exploitation détermine si les formes complètes et abrégées sont disponibles. Transmettez la valeur DateTimeNameStyle.FULL pour extraire les noms de mois complet. Transmettez la valeur DateTimeNameStyle.LONG_ABBREVIATION ou DateTimeNameStyle.SHORT_ABBREVIATION pour obtenir des versions abrégées. Dans certaines langues, un nom de mois change (il est alors mis au génitif) s’il est placé à côté de la valeur jour dans un format de date. Si vous envisagez d’utiliser les noms de mois sans spécifier de jour, transmettez la valeur DateTimeNameContext.STANDALONE à la méthode getMonthNames(). Pour utiliser les noms de mois dans les dates formatées, transmettez toutefois la valeur DateTimeNameContext.FORMAT. var dtf:DateTimeFormatter = new DateTimeFormatter("fr-FR"); var months:Vector.<String> = dtf.getMonthNames(DateTimeNameStyle.FULL, DateTimeNameContext.STANDALONE); trace(months[0]); // janvier months = dtf.getMonthNames(DateTimeNameStyle.SHORT_ABBREVIATION, DateTimeNameContext.STANDALONE); trace(months[0]); // janv.
Flash Player 10.1 et les versions ultérieures, Adobe AIR 2.0 et les versions ultérieures Le processus de disposition des éléments dans l’ordre approprié porte le nom de classement. Les règles de classement varient considérablement selon les paramètres régionaux sélectionnés. Elles varient également si vous triez une liste ou que vous mettez en correspondance des éléments similaires (dans un algorithme de recherche de texte, par exemple). Lors de l’exécution d’un tri, les différences mineures telles que la casse ou les signes diacritiques tels que les accents jouent souvent un rôle important. Ainsi, la lettre ö (o avec un tréma) est généralement considérée comme étant équivalente à la lettre o simple en français ou en anglais. En suédois, cette lettre suit cependant la lettre z. En français comme dans d’autres langues, la présence d’un caractère accentué dans un mot affecte l’ordre de tri d’une liste. Lors d’une recherche, il est souvent préférable de ne pas tenir compte de la casse ou des signes diacritiques pour augmenter les chances de détection de correspondances appropriées. Ainsi, la recherche des caractères « cote » dans un document français est susceptible de renvoyer « cote », « côte » et « coté ».
La classe Collator a pour principales méthodes compare(), qui sert principalement à trier, et equals(), qui permet de mettre en correspondance les valeurs. L’exemple suivant illustre le comportement des méthodes compare() et equals(). var words:Array = new
L’exemple crée ensuite un objet Collator en mode MATCHING. Lorsque l’objet Collator compare les deux mots, il les considère comme égaux. La comparaison MATCHING n’établit ainsi pas de distinction entre les caractères accentués et non accentués.
Par défaut, la classe Collator fait appel aux règles de comparaison de chaînes extraites du système d’exploitation, en fonction des paramètres régionaux et des préférences système de l’utilisateur. Pour personnaliser le comportement des méthodes compare() et equals(), définissez explicitement diverses propriétés. Le tableau suivant recense les propriétés et leur impact sur les comparaisons :
Les langues gèrent également différemment les règles de conversion des majuscules et des minuscules. Ainsi, dans la plupart des langues basées sur l’alphabet latin, la forme minuscule de la majuscule « I » est «i ». Toutefois, certaines langues, telles que le turc et l’azéri, comportent une autre lettre « ı » sans point. Par conséquent, dans ces langues, un « ı » minuscule sans point se transforme en « I » majuscule. Un « i » minuscule se transforme quant à lui en « İ » majuscule avec un point. La classe StringTools propose des méthodes qui font appel à des règles propres à chaque langue pour exécuter ces transformations.
La classe StringTools contient deux méthodes de transformation de la casse, toLowerCase() et toUpperCase(). Vous créez un objet StringTools en appelant le constructeur à l’aide d’un ID de paramètres régionaux. La classe StringTools extrait les règles de conversion de casse associées aux paramètres régionaux (ou à des paramètres régionaux de substitution) du système d’exploitation. Il est impossible de personnaliser plus encore l’algorithme de conversion de casse. L’exemple suivant fait appel aux méthodes toUpperCase() et toLowerCase() pour transformer une expression allemande qui comprend la lettre « ß » (Eszett).
L’application Global Stock Ticker extrait et affiche des données boursières fictives dans trois Bourses distinctes : EtatsUnis, Japon et Europe. Elle formate les données en fonction des conventions de divers paramètres régionaux. Cet exemple illustre les fonctions suivantes du package flash.globalization :
• Formatage des devises en fonction des paramètres régionaux • Définition des codes ISO et des symboles de devise • Formatage de date en fonction des paramètres régionaux • Extraction et affichage des abréviations de noms de mois appropriées Pour obtenir les fichiers d’application de cet exemple, voir www.adobe.com/go/learn_programmingAS3samples_flash_fr. Les fichiers d’application de Global Stock Ticker résident dans le dossier Samples/GlobalStockTicker. L’application se compose des fichiers suivants : Fichier
Les principaux éléments de l’interface utilisateur de l’application sont les suivants :
• Liste déroulante permettant de sélectionner une Bourse • Grille contenant les données de six sociétés par Bourse • Graphique illustrant les données historiques simulées des actions de la société sélectionnée L’application stocke tous les exemples de données relatifs aux paramètres régionaux, aux Bourses et aux actions des sociétés dans la classe StockDataModel. Une application réelle extrairait les données d’un serveur et les stockerait dans une classe telle que StockDataModel. Dans cet exemple, toutes les données sont codées en dur dans la classe StockDataModel. Remarque : les données affichées dans le graphique financier ne correspondent pas nécessairement pas aux données du contrôle grille de données. Le graphique est actualisé à chaque fois qu’une autre société est sélectionnée. Il est proposé à titre d’illustration uniquement.
Au terme de la phase de configuration initiale, l’application appelle la méthode Localizer.setLocale() pour créer des objets de formatage associés aux paramètres régionaux par défaut. La méthode setLocale() est également appelée à chaque fois que l’utilisateur sélectionne une nouvelle valeur dans la liste déroulante de paramètres régionaux.
Cette méthode affiche des messages d’erreur et d’avertissement sur la console en cas de problème au niveau des paramètres régionaux requis. (Une application réelle devrait réagir suite à des erreurs de ce type au lieu de se contenter de les suivre.)
Une fois l’objet DateTimeFormatter créé, la méthode setLocale() extrait également un tableau d’abréviations de noms de mois localisés.
Les données boursières formatées sont affichées dans un contrôle de type grille de données. Chaque colonne de la grille de données appelle une fonction d’étiquette qui formate la valeur de la colonne par le biais de l’objet de formatage approprié. Dans la version Flash, par exemple, le code suivant configure les colonnes de la grille de données : var col1:DataGridColumn = new DataGridColumn("ticker"); col1.headerText = "Company"; col1.sortOptions = Array.NUMERIC; col1.width = 200; var col2:DataGridColumn = new DataGridColumn("volume"); col2.headerText = "Volume"; col2.width = 120; col2.cellRenderer = RightAlignedCell; col2.labelFunction = displayVolume; var col3:DataGridColumn = new DataGridColumn("price"); col3.headerText = "Price"; col3.width = 70; col3.cellRenderer = RightAlignedCell; col3.labelFunction = displayPrice; var col4:DataGridColumn = new DataGridColumn("change"); col4.headerText = "Change"; col4.width = 120; col4.cellRenderer = RightAlignedCell; col4.labelFunction = displayPercent;
Les propriétés labelFunction font référence aux fonctions suivantes, qui appellent les méthodes de formatage de la classe Localizer :
« colour » dans les paramètres régionaux en_GB. Par ailleurs, les devises correspondraient aux dollars ou aux livres Sterling, selon les paramètres régionaux, et les formats de date et d’heure seraient peut-être aussi différents. Vous pouvez également fournir un jeu d’actifs pour une langue sans spécifier de code de pays. Ainsi, vous pouvez fournir des actifs en pour l’anglais et des actifs supplémentaires pour les paramètres régionaux fr_FR, qui sont spécifiques à l’anglais américain. La localisation ne se limite pas à traduire les chaînes utilisées dans l’application. Elle peut également comprendre n’importe quel type d’actif, tels que les fichiers audio, les images ou les vidéos.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour déterminer les jeux de paramètres régionaux qu’utilise votre contenu ou votre application, vous pouvez procéder comme suit, au choix :
« Identification des paramètres régionaux » à la page 981.
Adobe Flex propose une structure de localisation du contenu Flex. Cette structure contient les classes Locale, ResourceBundle et ResourceManagerImpl, ainsi que les interfaces IResourceBundle et IResourceManagerImpl. Une bibliothèque de localisation Flex contenant des classes d’utilitaires destinés à trier les paramètres régionaux d’application est proposée sur Google Code (http://code.google.com/p/as3localelib/).
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Adobe Flash Professional comprend une classe Locale dans les composants ActionScript 3.0. La classe Locale vous permet de contrôler l’affichage de texte multilingue dans un fichier SWF. Le panneau Chaînes de Flash vous permet d’utiliser des ID de chaîne au lieu de littéraux de chaîne dans les champs de texte dynamique. Grâce à cette fonctionnalité, vous pouvez créer un fichier SWF qui affiche du texte chargé à partir d’un fichier XML spécifique à une langue. Pour plus d’informations sur l’utilisation de la classe Locale, voir Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash.
Le SDK d’AIR propose une structure de localisation HTML (qui figure dans un fichier AIRLocalizer.js). Cette structure comprend des API qui facilitent la gestion de plusieurs paramètres régionaux dans une application HTML. Pour accéder à une bibliothèque ActionScript destinée à trier les paramètres régionaux, voir http://code.google.com/p/as3localelib/.
Vous pouvez écrire du code pour formater les dates, heures et devises. Par exemple, le code suivant convertit un objet Date du format mois/jour/année au format jour/mois/année. Si la variable locale (qui représente le jeu de paramètres régionaux) est définie sur fr_FR, la fonction renvoie le format mois/jour/année. L’exemple convertit un objet Date au format jour/mois/année pour tous les autres jeux de paramètres régionaux : function convertDate(date) { if (locale == "en_US") { return (date.getMonth() + 1) + "/" + date.getDate() + "/" + date.getFullYear(); } else HTML à l’aide des langages HTML et JavaScript. La plupart des pages et applications HTML existantes devraient être exécutées en présentant peu de modifications (à condition qu’elles utilisent des fonctions HTML, CSS, DOM et JavaScript compatibles avec WebKit). Important : les nouvelles versions du moteur d’exécution Adobe AIR comprennent parfois des versions mises à jour de WebKit. L’intégration d’une mise à jour de WebKit à une nouvelle version d’AIR risque d’engendrer des modifications inattendues dans une application AIR déployée. Ces modifications affectent parfois le comportement ou l’apparence du contenu HTML d’une application. Par exemple, les améliorations ou les corrections apportées au rendu WebKit ont parfois un impact sur les éléments de mise en forme de l’interface utilisateur d’une application. C’est pourquoi il est fortement recommandé d’intégrer un mécanisme de mise à jour à votre application. S’il s’avère nécessaire de mettre à jour votre application en raison d’une modification de la version de WebKit intégrée à AIR, le mécanisme de mise à jour d’AIR peut inviter l’utilisateur à installer la nouvelle version de votre application. Le tableau suivant répertorie les versions du navigateur Web Safari qui font appel à la version de WebKit correspondant à celle utilisée dans AIR : Version d’AIR 1.0 1.1 WebKit non prises en charge dans AIR » à la page 1015.
été chargés à partir du réseau à l’aide des protocoles http: ou https: sont dirigés vers un sandbox dépendant du domaine du serveur distant. L’accès à toute API AIR est interdit au contenu de ces sandbox qui ne sont pas des applications. Ce type de contenu est exécuté comme il le serait dans un navigateur Web classique. Le contenu HTML visible dans AIR n’affiche pas de contenu SWF ou PDF si des paramètres alpha, de mise à l’échelle ou de transparence sont appliqués. Pour plus d’informations, voir « Eléments à prendre en compte lors du chargement d’un contenu SWF ou PDF dans une page HTML » à la page 1045 et « Transparence de la fenêtre » à la page 927.
Webkit DOM Reference à son tour, compris dans un objet NativeWindow. Dans un contenu SWF, il est possible d’ajouter la classe HTMLLoader, qui étend la classe Sprite, à la liste d’affichage d’une scène à l’instar de tout autre objet d’affichage. Les propriétés Adobe® ActionScript® 3.0 de la classe sont décrites à la section « Programmation du conteneur HTML d’AIR à l’aide de scripts » à la page 1043 et dans le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash. Dans la structure Flex, la classe AIR HTMLLoader est enveloppée dans un composant mx:HTML. Comme le composant mx:HTML étend la classe UIComponent, il peut être directement utilisé avec d’autres conteneurs Flex. L’environnement JavaScript au sein du composant mx:HTML ne présente aucune autre différence.
Le diagramme suivant illustre la relation existant entre l’environnement JavaScript et l’environnement du moteur d’exécution AIR. Bien qu’une seule fenêtre native soit affichée, une application AIR peut contenir plusieurs fenêtres. (De même, une seule fenêtre peut comprendre de multiples objets HTMLLoader.)
ActionScript et JavaScript permettent d’écouter des événements envoyés à la fois par des objets AIR et JavaScript.
L’objet NativeWindow offre des propriétés permettant de contrôler la fenêtre du poste de travail. A partir d’une page HTML, vous pouvez accéder à l’objet NativeWindow conteneur à l’aide de la propriété window.nativeWindow. L’objet HTMLLoader propose des propriétés, des méthodes et des événements destinés à contrôler les modes de chargement et de rendu du contenu. A partir d’une page HTML, vous pouvez accéder à l’objet HTMLLoader parent à l’aide de la propriété window.htmlLoader.
Adobe AIR 1.0 et les versions ultérieures AIR exécute la totalité du code au sein d’un sandbox de sécurité dépendant du domaine d’origine. Le contenu de l’application, qui se limite au contenu chargé à partir du répertoire d’installation de l’application, est placé dans le sandbox de l’application. L’accès à l’environnement d’exécution et aux API AIR est uniquement disponible pour les scripts HTML et JavaScript exécutés dans ce sandbox. Parallèlement à cela, les opérations d’évaluation et d’exécution dynamiques de code JavaScript sont en grande partie bloquées dans le sandbox de l’application une fois que tous les gestionnaires de l’événement load de la page ont été renvoyés. Vous avez la possibilité de mapper une page d’application dans un sandbox autre que d’application. Pour ce faire, chargez la page dans une image ou une iframe et définissez les attributs sandboxRoot etdocumentRoot du cadre propres à AIR. En configurant la valeur de sandboxRoot sur un domaine distant réel, vous permettez au contenu placé dans le sandbox d’intercoder le contenu de ce domaine. Cette méthode de mappage de pages peut s’avérer pratique lors du chargement et du codage du contenu distant, dans le cadre d’une application composite par exemple. Une autre solution permettant d’intercoder des contenus d’application et autre (et la seule manière de donner accès à des API AIR à un contenu autre que d’application) consiste à créer un pont de sandbox. Un pont parent-enfant permet au contenu d’une image enfant, d’une iframe ou d’une fenêtre d’accéder à des méthodes et propriétés désignées définies dans le sandbox de l’application. A l’inverse, un pont enfant-parent permet au contenu de l’application d’accéder à des méthodes et propriétés désignées définies dans le sandbox de l’enfant. Pour définir un pont de sandbox, vous devez définir les propriétés parentSandboxBridge et childSandboxBridge de l’objet window. Pour plus d’informations, voir « Sécurité HTML dans Adobe AIR » à la page 1127 et « Eléments image et iframe HTML » à la page 1011.
Adobe AIR 1.0 et les versions ultérieures AIR prend en charge le module d’extension Adobe® Acrobat®. Pour afficher le contenu PDF, les utilisateurs doivent disposer d’Acrobat ou d’Adobe® Reader® 8.1 (ou version ultérieure). L’objet HTMLLoader comprend une propriété permettant de vérifier si le système d’un utilisateur peut afficher ou non des documents PDF. Il est également possible d’afficher le contenu des fichiers SWF au sein de l’environnement HTML. Cette fonction étant intégrée dans AIR, elle ne fait appel à aucun module d’extension. AIR ne prend en charge aucun autre module d’extension Webkit.
« Sécurité HTML dans Adobe AIR » à la page 1127 « Sandbox HTML » à la page 1003 « Eléments image et iframe HTML » à la page 1011
AIR et WebKit Adobe AIR 1.0 et les versions ultérieures Adobe AIR a recours au moteur Webkit, disponible en open source et également utilisé dans le navigateur Web Safari. AIR ajoute plusieurs extensions pour accéder aux objets et aux classes d’exécution ainsi que pour des raisons de sécurité. En outre, Webkit lui-même insère des fonctions non incluses dans les normes W3C des langages HTML, CSS et JavaScript. Seuls les ajouts d’AIR et les extensions Webkit les plus significatives sont traités dans cette section. Pour obtenir des informations complémentaires sur les langages HTML, CSS et JavaScript non standard, voir www.webkit.org et developer.apple.com. Pour plus d’informations sur les normes, consulter le site Web W3C. Mozilla propose également une page de référence très intéressante portant sur les technologies HTML, CSS et DOM (bien évidemment, les moteurs Webkit et Mozilla sont différents l’un de l’autre).
AIR apporte plusieurs modifications au comportement classique des objets JavaScript courants. La plupart de ces modifications sont destinées à simplifier l’écriture d’applications sécurisées dans AIR. Parallèlement à cela, ces différences de comportement impliquent que certains modèles de codage JavaScript courants et les applications Web existantes qui s’en servent risquent de ne pas fonctionner comme prévu dans AIR. Pour plus d’informations sur la correction de ces types de problèmes, voir la section « Contournement des erreurs JavaScript liées à la sécurité » à la page 1021.
AIR place les différents contenus dans des sandbox distincts en fonction de leur origine. Les règles de sandbox respectent la stratégie de « même origine » implémentée par la plupart des navigateurs Web, de même que les règles applicables aux sandbox mises en œuvre par Adobe Flash Player. AIR propose en outre un nouveau type de sandbox d’application conçu pour contenir et protéger le contenu de l’application. Pour plus d’informations sur les types de sandbox que vous êtes susceptible de rencontrer lors du développement d’applications AIR, voir « Sandbox de sécurité » à la page 1087. L’accès à l’environnement d’exécution et aux API AIR est uniquement disponible pour les scripts HTML et JavaScript exécutés dans le sandbox de l’application. Parallèlement à cela, toutefois, les opérations d’évaluation et d’exécution dynamiques de code JavaScript, sous leurs diverses formes, sont largement limitées au sein du sandbox de l’application pour des raisons de sécurité. Ces restrictions s’appliquent que votre application charge réellement ou non des informations directement depuis un serveur. (Même le contenu des fichiers, les chaînes collées et les données saisies directement par l’utilisateur peuvent ne pas être fiables.)
Pour qu’une page d’application puisse interagir librement avec un contenu situé dans un sandbox distant, vous pouvez la mapper au même domaine que le contenu distant. Si, par exemple, vous écrivez une application affichant des données de mappage provenant d’un service Internet, la page de l’application qui est chargée et qui présente le contenu émanant du service pourrait être mappée au domaine du service. Les attributs de mappage des pages dans un sandbox et un domaine distants sont de nouveaux attributs ajoutés aux éléments image et iframe HTML. Pour permettre à un contenu d’un sandbox autre que d’application d’utiliser les fonctions d’AIR en toute sécurité, vous pouvez configurer un pont de sandbox parent. Pour permettre au contenu de l’application d’appeler des méthodes et des propriétés d’accès de contenu en toute sécurité dans d’autres sandbox, configurez un pont de sandbox enfant. La notion de sécurité évoquée ici signifie que le contenu distant ne peut pas obtenir accidentellement de références à des objets, des propriétés ou des méthodes exposés de manière non explicite. Seuls les objets anonymes, fonctions et types de données simples peuvent être transmis via le pont. Vous devez néanmoins éviter d’exposer explicitement des fonctions potentiellement dangereuses. Si, par exemple, vous avez exposé une interface qui autorisait le contenu distant à lire et à écrire des fichiers n’importe où sur le système d’un utilisateur, vous risquez de donner à ce contenu les moyens de nuire considérablement aux utilisateurs.
Adobe AIR 1.0 et les versions ultérieures L’utilisation de la fonction eval() est limitée au contenu du sandbox de l’application une fois le téléchargement de la page terminé. Dans certains cas, cette fonction peut servir à analyser en toute sécurité des données au format JSON, mais toute évaluation aboutissant à des résultats d’instructions exécutables se traduit par une erreur. La section « Restrictions relatives au code pour un contenu dans des sandbox différents » à la page 1130 décrit les utilisations autorisées pour la fonction eval().
Adobe AIR 1.0 et les versions ultérieures Dans le sandbox d’application, il est possible d’utiliser des constructeurs de fonctions avant la fin du chargement d’une page. Dès lors que tous les gestionnaires d’événement load de page sont terminés, il est impossible de créer de nouvelles fonctions.
Adobe AIR 1.0 et les versions ultérieures Les pages HTML du sandbox de l’application ne peuvent pas utiliser la balise script pour charger des fichiers JavaScript situés en dehors du répertoire de l’application. Pour qu’une page de votre application puisse charger un script stocké en dehors du répertoire de l’application, vous devez la mapper dans un sandbox autre que celui de d’application.
Par défaut, AIR bloque les requêtes XMLHttpRequest interdomaines dans les sandbox autres que d’application. Une fenêtre parent du sandbox de l’application peut choisir d’autoriser des requêtes interdomaines dans une image enfant dont le contenu ne se trouve pas dans un sandbox autre que d’application. Pour ce faire, définissez allowCrossDomainXHR, un attribut ajouté par AIR, sur la valeur true dans l’élément image ou iframe conteneur : <iframe id="mashup" src="http://www.example.com/map.html" allowCrossDomainXHR="true" </iframe>
Si vous distribuez une requête XMLHttpRequest vers un serveur distant à partir d’une image ou d’une iframe doté du contenu de l’application mappé dans un sandbox distant, assurez-vous que l’URL de mappage ne masque pas l’adresse du serveur utilisé dans la requête XHR. Tenez compte, par exemple, de la définition d’iframe suivante, laquelle mappe le contenu de l’application dans un sandbox distant pour le domaine example.com : <iframe id="mashup" src="http://www.example.com/map.html" documentRoot="app:/sandbox/" sandboxRoot="http://www.example.com/" allowCrossDomainXHR="true" </iframe>
Afin d’éviter de bloquer accidentellement des requêtes de données en direction du serveur distant, mappez sandboxRoot à un sous-répertoire de l’URL distante plutôt qu’à la racine. Le répertoire ne doit pas nécessairement exister. Par exemple, pour permettre le chargement des requêtes en direction de www.example.com à partir du serveur distant plutôt que du répertoire de l’application, modifiez l’iframe précédente de la manière suivante :
« Sécurité HTML dans Adobe AIR » à la page 1127.
Adobe AIR 1.0 et les versions ultérieures Dans les applications AIR, seul le contenu des sandbox distants (chargé à partir de sources http: et https:) peut utiliser des cookies (propriété document.cookie). Le sandbox d’application propose d’autres techniques de stockage des données persistantes, telles que les classes EncryptedLocalStore, SharedObject et FileStream.
Adobe AIR 1.0 et les versions ultérieures L’API Clipboard de WebKit est dotée des événements suivants : copy, cut et paste. L’objet événement transmis dans ces événements permet d’accéder au Presse-papiers via la propriété clipboardData. Faites appel aux méthodes suivantes de l’objet clipboardData pour lire ou écrire des données de Presse-papiers : Méthode
Les types MIME de données valides sont les suivants :
Adobe AIR 1.0 et les versions ultérieures Les mouvements de glisser-déposer vers et depuis un contenu HTML génèrent les événements DOM suivants : dragstart, drag, dragend, dragenter, dragover, dragleave et drop. L’objet événement transmis dans ces événements permet d’accéder aux données déplacées via la propriété dataTransfer. La propriété dataTransfer fait référence à un objet offrant les mêmes méthodes que l’objet clipboardData associé à un événement clipboard. Par exemple, la fonction suivante pourrait servir à obtenir des données au format texte à partir d’un événement drop : function onDrop(dragEvent){ return dragEvent.dataTransfer.getData("text/plain", air.ClipboardTransferMode.ORIGINAL_ONLY); }
Pour plus d’informations sur l’ajout de la prise en charge du glisser-déposer à une application AIR, voir « Opération glisser-déposer dans AIR » à la page 629 et Using the Drag-and-Drop from JavaScript (centre de développeurs Apple).
<script> intégrées ne sont pas évaluées. Pour plus d’informations, voir « Sécurité HTML dans Adobe AIR » à la page 1127.
Adobe AIR 1.0 et les versions ultérieures L’utilisation des méthodes write() et writeln() n’est pas limitée dans le sandbox de l’application avant la survenue de l’événement load de la page. Toutefois, dès lors que la page est chargée, l’appel de l’une ou l’autre de ces méthodes n’efface pas la page ou n’en crée pas de nouvelle. Dans un sandbox autre que celui de l’application, comme dans la plupart des navigateurs Web, l’appel de la méthode document.write() ou writeln() après la fin du chargement de la page entraîne l’effacement de la page active et l’ouverture d’une nouvelle page vide.
Adobe AIR 1.0 et les versions ultérieures Définissez la propriété document.designMode sur la valeur on afin de rendre tous les éléments du document modifiables. L’éditeur intégré prend en charge les modifications de texte, la copie, le collage et le glisser-déposer. Définir designMode sur on revient au même que configurer la propriété contentEditable de l’élément body sur la valeur true. La propriété contentEditable permet de définir les sections modifiables d’un document pour la plupart des éléments HTML. Pour plus d’informations, voir la section « Attribut contentEditable HTML » à la page 1014.
Adobe AIR 1.0 et les versions ultérieures Dans la balise frameset ou body de niveau supérieur d’une fenêtre (y compris la fenêtre principale de l’application), ne répondez pas à la fenêtre (ou à l’application) en cours de fermeture au moyen de l’événement unload. Au lieu de cela, optez pour l’événement exiting de l’objet NativeApplication (afin de détecter le moment de fermeture d’une application). Une autre solution consiste à utiliser l’événement closing de l’objet NativeWindow (afin de détecter le moment de fermeture d’une fenêtre). Par exemple, le code JavaScript suivant affichage un message (« Goodbye ») lorsque l’utilisateur ferme l’application : var app = air.NativeApplication.nativeApplication; app.addEventListener(air.Event.EXITING, closeHandler); function closeHandler(event) { alert("Goodbye."); }
intégrées à partir du sandbox de l’application. Ces classes comprennent les API AIR et Flash Player (mais pas, par exemple, la structure Flex). L’instruction suivante crée par exemple un objet de fichier AIR : var preferencesFile = new window.runtime.flash.filesystem.File();
File à l’aide de l’instruction suivante : var preferencesFile = new air.File();
Voir la section « Utilisation du fichier AIRAliases.js » à la page 1027. Propriété Window.nativeWindow La propriété nativeWindow fournit une référence à l’objet window natif sous-
La propriété window.nativeWindow est exclusivement définie pour un contenu situé dans le sandbox de l’application et pour le document parent d’une page dotée d’images ou d’iframes. Propriété Window.htmlLoader La propriété htmlLoader fournit une référence à l’objet HTMLLoader AIR disposant
HTML. Vous pouvez ainsi utiliser la propriété htmlLoader.paintsDefaultBackground afin de déterminer si la commande dessine un arrière-plan blanc par défaut : window.htmlLoader.paintsDefaultBackground = false;
Window JavaScript du contenu HTML inclus. Cette propriété vous permet d’accéder à l’environnement JavaScript via une référence à l’objet HTMLLoader conteneur. La propriété window.htmlLoader est exclusivement définie pour un contenu situé dans le sandbox de l’application et pour le document parent d’une page dotée d’images ou d’iframes. Propriétés Window.parentSandboxBridge et Window.childSandboxBridge Les propriétés parentSandboxBridge et childSandboxBridge vous permettent de définir une interface entre un cadre parent et un cadre enfant. Pour plus
Adobe AIR 1.0 et les versions ultérieures L’objet NativeApplication fournit des informations sur l’état de l’application, distribue différents événements de niveau application importants et offre des fonctions pratiques de contrôle du comportement de l’application. Une occurrence unique de l’objet NativeApplication est créée automatiquement. Elle est accessible via la propriété NativeApplication.nativeApplication définie dans la classe. Pour accéder à l’objet à partir du code JavaScript, vous pouvez utiliser : var app = window.runtime.flash.desktop.NativeApplication.nativeApplication;
Adobe AIR 1.0 et les versions ultérieures L’exécution d’un code défini dans un modèle d’URL JavaScript (comme dans href="javascript:alert('Test')") est bloquée au sein du sandbox de l’application. Aucune erreur n’est renvoyée.
AIR et WebKit définissent deux éléments et attributs HTML non standard, à savoir : « Eléments image et iframe HTML » à la page 1011 « Gestionnaires d’événement d’élément HTML » à la page 1013
Attribut sandboxRoot L’attribut sandboxRoot spécifie un domaine de remplacement autre que d’application d’origine pour le fichier indiqué par l’attribut src du cadre. Le fichier est chargé dans le sandbox autre que d’application correspondant au domaine précisé. Le contenu du fichier et celui chargé à partir du domaine indiqué peuvent être intercodés.
Attribut documentRoot L’attribut documentRoot indique le répertoire local à partir duquel sont chargées les URL renvoyant à des fichiers situés à l’emplacement spécifié par sandboxRoot.
<iframe src="http://www.example.com/air/child.html" documentRoot="app:/sandbox/" sandboxRoot="http://www.example.com/air/"/> child.html est chargé depuis le sous-répertoire sandbox du dossier d’installation de l’application. Les URL relatives contenues dans child.html sont résolues en fonction du répertoire sandbox. Vous noterez que les fichiers situés sur le serveur distant à l’adresse www.example.com/air ne sont pas accessibles dans le cadre, car AIR tenterait sinon de les charger à partir du répertoire app:/sandbox/.
Important : si l’attribut allowCrossDomainXHR se trouve dans un élément image ou iframe, les requêtes XHR interdomaines sont activées (à moins que la valeur attribuée soit égale à 0 ou commence par les lettres f ou n). Par exemple, définir allowCrossDomainXHR sur la valeur deny maintient l’activation des requêtes XHR interdomaines. Excluez totalement l’attribut de la déclaration d’élément si vous préférez ne pas activer les requêtes interdomaines. ondominitialize, attribut Indique un gestionnaire d’événement pour l’événement dominitialize d’un cadre. Cet
Le cadre distribue l’événement dominitialize suffisamment tôt dans la séquence de chargement pour qu’un script de la page enfant puisse référencer les objets, variables et fonctions ajoutés au document enfant par le gestionnaire dominitialize. La page parent doit se trouver dans le même sandbox que l’enfant pour pouvoir insérer ou ouvrir
Les exemples suivants illustrent l’utilisation de la balise iframe dans AIR : Placez child.html dans un sandbox distant, sans définir de mappage à un domaine réel situé sur un serveur distant : <iframe src="http://localhost/air/child.html" documentRoot="app:/sandbox/" sandboxRoot="http://localhost/air/"/>
<iframe src="http://www.example.com/air/child.html" documentRoot="app:/sandbox/" sandboxRoot="http://www.example.com/air/"/> Nom de l’attribut de rappel Description oncontextmenu
Document.designMode » à la page 1008.
Adobe AIR 2 et ultérieur AIR prend en charge les URL de type data: pour les éléments suivants :
• input type=”image” • Règles CSS qui autorisent les images (telles les images d’arrière-plan) Les URL de type data: permettent d’insérer directement des données d’images binaires dans un document CSS ou HTML sous forme de chaîne codée au format base64. L’exemple suivant utilise une URL de type data: sous forme d’arrière-plan répété : <html> <head> CSS dans AIR Adobe AIR 1.0 et les versions ultérieures WebKit prend en charge plusieurs propriétés CSS étendues. Un grand nombre de ces extensions utilisent le préfixe webkit. Notez que certaines de ces extensions sont d’ordre expérimental et risquent d’être supprimées d’une version
CSS Reference (disponible en anglais uniquement).
AIR ne prend pas en charge les fonctions suivantes disponibles dans WebKit ou Safari 4 :
Membres d’objet Window JavaScript non pris en charge : • applicationCache() HTML et JavaScript. Les informations qui suivent sont importantes, que vous programmiez une application AIR à base d’HTML ou bien sur SWF qui exécute HTML et JavaScript à l’aide de la classe HTMLLoader (ou du composant mx:HTML Flex™).
Adobe AIR 1.0 et les versions ultérieures La classe HTMLLoader d’Adobe AIR définit l’objet d’affichage qui peut afficher du contenu HTML dans une application AIR. Les applications basées sur SWF peuvent ajouter un contrôle HTMLLoader à une fenêtre existante ou créer une fenêtre HTML qui contienne automatiquement un objet HTMLLoader avec HTMLLoader.createRootWindow(). Il est possible d’accéder à l’objet HTMLLoader via la propriété window.htmlLoader de JavaScript au sein de la page HTML chargée.
Le code suivant charge une URL dans un objet HTMLLoader (ajoutez le HTMLLoader en tant qu’enfant de la scène ou tout autre conteneur d’objet d’affichage pour afficher le contenu HTML dans votre application) : import flash.html.HTMLLoader; var html:HTMLLoader = new HTMLLoader; html.width = 400; html.height = 600; var urlReq:URLRequest = new URLRequest("http://www.adobe.com/"); html.load(urlReq);
événements à mesure qu’une page se charge. Vous pouvez utiliser ces événements pour déterminer à quel moment on peut interagir sans risque avec la page chargée. Ces événements sont décrits dans la section « Gestion des événements HTML dans AIR » à la page 1062. Remarque : dans la structure Flex, seules les classes qui étendent la classe UIComponent peuvent être ajoutées en tant qu’enfants de composants d’un conteneur Flex. C’est pour cette raison que vous ne pouvez pas ajouter directement un HTMLLoader en tant qu’enfant d’un composant de conteneur Flex. Toutefois, vous pouvez utiliser le contrôle mx:HTML de Flex, construire une classe personnalisée qui étend l’UIComponent et contient un HTMLLoader comme enfant d’un UIComponent ou bien ajouter le HTMLLoader en tant qu’enfant d’un UIComponent et ajouter l’UIComponent au conteneur Flex.
TextField d’Adobe® Flash® Player prend en charge un sous-ensemble du balisage de HTML ; mais, en raison de restrictions de taille, ses capacités sont réduites. La classe HTMLLoader contenue dans Adobe AIR n’est pas disponible dans Flash Player.
Adobe AIR 1.0 et les versions ultérieures La méthode loadString() d’un objet HTMLLoader charge une chaîne de contenu HTML dans un objet HTMLLoader : var html:HTMLLoader = new HTMLLoader(); var htmlStr:String = "<html><body>Hello <b>world</b>.</body></html>"; html.loadString(htmlStr);
• Il ne peut pas charger les données avec XMLHttpRequest. • La propriété window.location est définie sur "about:blank". • Le contenu ne peut pas accéder à la propriété window.runtime (alors que le contenu placé dans tout sandbox non applicatif le peut). Dans AIR 1.5, la classe HTMLLoader comprend une propriété placeLoadStringContentInApplicationSandbox. Lorsque cette propriété est définie sur true pour un objet HTMLLoader, le contenu chargé par la méthode loadString() est placé dans le sandbox de l’application. (La valeur par défaut est false.) Le contenu chargé par la méthode loadString() a ainsi accès à la propriété window.runtime et à toutes les API AIR. Si vous définissez cette propriété sur true, assurez-vous que la source des données d’une chaîne utilisée dans un appel à la méthode loadString() soit approuvée. Les instructions du code de la chaîne HTML sont exécutées avec tous les privilèges de l’application lorsque cette propriété est définie sur true. Ne définissez cette propriété sur true que si vous êtes certain(e) que la chaîne ne contient que du code inoffensif. Dans les applications compilées avec les kits SDK d’AIR 1.0 ou AIR 1.1, le contenu chargé par la méthode loadString() est placé dans le sandbox de l’application.
Les fichiers que vous installez avec l’application AIR ont accès aux interfaces de programmation d’AIR. Pour des raisons de sécurité, ce n’est pas le cas pour du contenu provenant d’autres sources. Par exemple, une telle restriction empêche le contenu provenant d’un domaine distant, comme http://example.com, de lire le contenu du répertoire dans l’ordinateur de bureau de l’utilisateur (ou pire encore). Comme il est possible d’exploiter des failles de sécurité en appelant la fonction eval() et les interfaces de programmation qui lui sont liées, l’utilisation de ces méthodes est interdite, par défaut, au contenu installé avec l’application. Toutefois, quelques structures Ajax utilisent la fonction eval() et les interfaces de programmation qui lui sont liées.
Si vous appelez du code interdit d’exécution dans un sandbox pour des raisons de sécurité, une erreur JavaScript est signalée par le message : « Violation des règles de sécurité d’Adobe AIR par du code JavaScript dans le sandbox de sécurité de l’application ». Pour éviter cette erreur, suivez les règles de codage présentées dans la section suivante, « Contournement des erreurs JavaScript liées à la sécurité » à la page 1021. Pour plus d’informations, voir « Sécurité HTML dans Adobe AIR » à la page 1127.
Adobe AIR 1.0 et les versions ultérieures Si vous appelez du code interdit d’exécution dans un sandbox en raison de ces restrictions liées à la sécurité, le moteur d’exécution distribue une erreur JavaScript : « Violation des règles de sécurité dans le sandbox de sécurité de l’application par le moteur d’exécution d’Adobe AIR sur du code JavaScript ». Pour éviter cette erreur, suivez les règles de codage suivantes.
Adobe AIR 1.0 et les versions ultérieures Le code qui s’exécute dans le sandbox de l’application ne peut pas exécuter des opérations qui impliquent l’évaluation et l’exécution de chaînes dès le moment où l’événement load est lancé et que les gestionnaires d’événement load ne sont plus actifs. Les tentatives d’utilisation des types suivants d’instructions JavaScript, qui évaluent et exécutent des chaînes potentiellement non protégées, génèrent des erreurs JavaScript.
• setTimeout() et setInterval() • Constructeur Function De plus, les types d’instructions JavaScript suivants échouent sans générer une erreur JavaScript risquée :
• document.write() et document.writeln() • XMLHttpRequests synchrones lancées avant l’événement load ou au cours de l’exécution d’un gestionnaire d’événement load
Remarque : dans des cas bien particuliers, l’évaluation de chaînes est autorisée. Pour plus d’informations, voir « Restrictions relatives au code pour un contenu dans des sandbox différents » à la page 1130. Adobe gère une liste de structures Ajax reconnues pour leur prise en charge du sandbox de sécurité d’application à l’adresse http://www.adobe.com/go/airappsandboxframeworks_fr. Les sections ci-dessous décrivent comment réécrire des scripts pour éviter d’obtenir ces erreurs JavaScript risquées et ces échecs silencieux lors de l’exécution de code dans le sandbox de l’application.
Adobe AIR 1.0 et les versions ultérieures Le plus souvent, vous pouvez réécrire ou restructurer une application pour éviter des erreurs JavaScript liées à la sécurité. Toutefois, lorsque la réécriture ou la restructuration s’avèrent impossibles, vous pouvez charger le contenu de l’application dans un sandbox différent à l’aide de la technique décrite à la section « Chargement du contenu de l’application dans un sandbox hors application » à la page 1039. Si ce contenu doit également accéder aux interfaces de programmation d’AIR, vous pouvez créer un pont de sandbox, tel que décrit à la section « Configuration d’une interface de pont de sandbox » à la page 1040.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Dans le sandbox de l’application, la fonction eval() ne peut être utilisée qu’avant l’exécution de l’événement load de page ou qu’en cours d’exécution d’un gestionnaire d’événement load. Après le chargement de la page, les appels à eval() n’exécuteront pas de code. Toutefois, dans les situations suivantes, il vous est possible de réécrire le code pour éviter d’utiliser eval().
Adobe AIR 1.0 et les versions ultérieures Au lieu d’analyser une chaîne pour construire l’accesseur propriété : eval("obj." + propName + " = " + val);
Adobe AIR 1.0 et les versions ultérieures Remplacez les instructions telles que les suivantes :
Remplacez la chaîne passée en tant que fonction gestionnaire avec une référence de fonction ou un objet de fonction. Par exemple, remplacez une instruction telle que : setTimeout("alert('Timeout')", 100);
Le code défini dans un lien à l’aide du modèle javascript: URL est ignoré dans le sandbox de l’application. Aucune erreur JavaScript risquée n’est générée. Vous pouvez remplacer des liens à l’aide d’URL JavaScript: telles que : <a href="javascript:code()">Click Me</a>
<a href="#" onclick="code()">Click Me</a>
<div id="container"></div>
'<a href="#" onclick="code()">Click Me.</a>'; Le chargement de fichiers de script à partir d’emplacements hors du sandbox de l’application n’est pas autorisé. Aucun message d’erreur sur la sécurité n’est généré. Tous les fichiers de script qui s’exécutent dans le sandbox de l’application doivent être installés dans le répertoire de l’application. Pour utiliser des scripts externes dans une page, il vous faut mapper la page dans un sandbox distinct. Voir la section « Chargement du contenu de l’application dans un sandbox hors application » à la page 1039.
Adobe AIR 1.0 et les versions ultérieures Les appels à document.write() ou document.writeln() sont ignorés après le traitement de l’événement load de la page. Aucun message d’erreur sur la sécurité n’est généré. Vous pouvez également charger un nouveau fichier ou remplacer le corps du document à l’aide des techniques de manipulation du DOM :
Adobe AIR 1.0 et les versions ultérieures Les XMLHttpRequests synchrones lancées avant l’événement load de la page ou au cours du traitement d’un événement load ne renvoient pas de contenu. Les XMLHttpRequests asynchrones peuvent être lancées, mais elles ne renvoient rien avant la fin de l’événementload. Après le traitement de l’événement load, les XMLHttpRequests synchrones se comportent normalement.
Accès aux classes de l’API AIR à partir de JavaScript Adobe AIR 1.0 et les versions ultérieures En plus des éléments standard et étendus du Webkit, HTML et le code JavaScript peuvent accéder aux classes hôtes par le moteur d’exécution. Ces classes vous permettent d’accéder aux fonctions avancées fournies par AIR et notamment :
• Utilisation des bases de données SQL locales • Contrôle des menus Fenêtre et de l’application • Accès aux sockets pour la mise en réseau • Utilisation des classes et objets définis par l’utilisateur • Capacités de sonorisation Par exemple, l’API de fichiers d’AIR comprend une classe File contenue dans le package flash.filesystem Vous pouvez créer un objet File en JavaScript comme suit : var myFile = new window.runtime.flash.filesystem.File();
Remarque : la propriété runtime n’est pas automatiquement ajoutée aux objets window des pages chargées dans une image ou dans une iframe. Toutefois, tant que le document enfant se trouve dans le sandbox de l’application, l’enfant peut accéder à la propriété runtime du parent. La structure du package des classes runtime demanderait aux développeurs de taper de longues chaînes de code JavaScript pour accéder à chaque classe, comme dans window.runtime.flash.desktop.NativeApplication. C’est pourquoi le SDK d’AIR contient un fichier AIRAliases.js qui vous permet d’accéder à des classes runtime beaucoup plus facilement, par exemple en tapant tout simplement air.NativeApplication. Les classes de l’interface de programmation AIR sont abordées tout au long du présent guide. D’autres classes de l’interface de programmation Flash Player, qui peuvent intéresser les développeurs HTML, sont décrites dans le manuel Adobe AIR API Reference for HTML Developers (disponible en anglais uniquement). ActionScript est le langage utilisé dans le contenu SWF (Flash Player). Toutefois, la syntaxe de JavaScript et celle d’ActionScript sont très proches. Elles sont toutes deux basées sur des versions du langage ECMAScript. Toutes les classes intégrées sont disponibles à la fois en JavaScript (dans un contenu HTML) et en ActionScript (dans un contenu SWF). Remarque : le code JavaScript ne peut utiliser les classes Dictionary, XML et XMLList qui sont disponibles dans ActionScript.
Pour utiliser le fichier AIRAliases.js, insérez la référence script suivante dans votre page HTML : <script src="AIRAliases.js"></script>
Important : sauf indication contraire, le code JavaScript présenté dans cette documentation à titre d’exemple suppose que vous avez inclus le fichier AIRAliases.js dans votre page HTML.
Dans un contenu HTML qui s’exécute sous AIR, vous pouvez utiliser les modèles d’URL suivants lorsque vous définissez les attributs src pour les balises img, frame, iframe et script, dans l’attribut href d’une balise link ou dans tout autre emplacement où vous pouvez fournir une URL.
Adobe AIR 1.0 et les versions ultérieures Le JavaScript dans la page HTML chargée par un objet HTMLLoader peut appeler les classes, les objets et les fonctions définis dans le contexte d’exécution d’ActionScript à l’aide des propriétés window.runtime, window.htmlLoader et window.nativeWindow de la page HTML. Par la création de références aux objets et fonctions ActionScript au sein d’un contexte d’exécution de JavaScript, vous pouvez également mettre ceux-ci à la disposition du code JavaScript.
Adobe AIR 1.0 et les versions ultérieures L’exemple ci-dessous décrit comment ajouter des propriétés qui font référence à des objets dans l’objet window global d’une page HTML.
Programmation HTML et JavaScript dans AIR
} var urlReq:URLRequest = new URLRequest("test.html"); html.addEventListener(Event.COMPLETE, loaded); html.load(urlReq); function loaded(e:Event):void{ html.window.foo = foo; html.window.helloFromJS = helloFromJS; Adobe AIR 1.0 et les versions ultérieures Pour mettre les classes ActionScript de votre application à la disposition de JavaScript, vous pouvez affecter le contenu HTML chargé au domaine de l’application qui contient les définition de classes. Le domaine d’application du contexte d’exécution de JavaScript peut être défini avec la propriété runtimeApplicationDomain de l’objet HTMLLoader. Pour définir le domaine d’application sur le domaine d’application principal, par exemple, définissez runtimeApplicationDomain sur ApplicationDomain.currentDomain, comme le montre le code ci-dessous : html.runtimeApplicationDomain = ApplicationDomain.currentDomain;
Adobe AIR 1.0 et les versions ultérieures Lorsque vous ajoutez des écouteurs d’événement à des objets hors de la page en cours, y compris des objets d’exécution, des objets dans du contenu SWF chargé et même des objets JavaScript qui s’exécutent dans d’autres pages, vous devriez toujours supprimer les écouteurs d’événement lorsque la page décharge. Autrement, l’écouteur d’événement distribue l’événement à une fonction de gestionnaire qui n’existe plus. Si cela se produit, le message d’erreur suivant s’affiche : « The application attempted to reference a JavaScript object in an HTML page that is no longer loaded » (L’application a tenté de référencer un objet JavaScript sur une page HTML qui n’est plus chargée). La suppression d’écouteurs d’événement qui ne sont plus utiles permet aussi à AIR de récupérer la mémoire qui leur est associée. Pour plus d’informations, voir la section « Suppression d’écouteurs d’événement sur une page HTML de navigation » à la page 1067.
Adobe AIR 1.0 et les versions ultérieures Dès que l’objet HTMLLoader distribue l’événement complete, vous pouvez accéder à tous les objets dans le DOM (ou document object model) HTML pour la page. Les objets accessibles sont les éléments d’affichage, tels que les objets div et p dans la page, ainsi que les variables et fonctions JavaScript. L’événement complete correspond à l’événement load de la page JavaScript. Avant que complete ne soit distribué, les éléments DOM, les variables et les fonctions peuvent ne pas avoir été analysés ou créés. Si possible, attendez l’événement complete avant d’accéder au DOM HTML. Par exemple, examinez la page HTML suivante : <html> <script> foo = 333; function test() { return "OK."; } Dernière mise à jour le 27/4/2013
Vous pouvez intégrer un contenu SWF dans un contenu HTML au sein d’une application AIR comme vous le feriez dans un navigateur. Intégrez le contenu SWF à l’aide d’une balise object, d’une balise embed ou de toutes les deux. Remarque : une pratique courante de développement sur le Web consiste à utiliser à la fois une balise object et une balise embed pour afficher un contenu SWF dans une page HTML. Vous ne tirez aucun avantage de cette pratique avec AIR. Vous pouvez utilisez la seule balise object, conforme à la norme W3C, dans le contenu pour l’afficher dans AIR. Cependant, vous pouvez continuer à utiliser les balises object et embed ensemble, le cas échéant, pour du contenu HTML qui est également affiché dans un navigateur. Si vous avez activé la transparence dans l’objet NativeWindow qui affiche le contenu HTML et SWF, AIR n’affiche pas le contenu SWF lorsque le mode Fenêtre (wmode) activé pour intégrer le contenu est défini sur la valeur window. Pour afficher le contenu SWF dans une page HTML de fenêtre transparente, définissez le paramètre wmode sur opaque ou transparent. Etant donné que le paramètre window correspond à la valeur par défaut de wmode, le contenu risque de ne pas être affiché si vous ne stipulez pas de valeur.
L’exemple suivant explique comment charger les actifs externes via un objet SWF incorporé dans un contenu HTML :
Accédez aux classes importées par la propriété runtime de l’objet Window de JavaScript : var libraryObject = new window.runtime.LibraryClass();
Pour accéder à des objets dans une page HTML à partir d’ActionScript dans un fichier SWF importé dans la page à l’aide de la balise <script>, transmettez une référence à l’objet JavaScript, telle que window ou document, à une fonction définie dans le code ActionScript. Utilisez la référence au sein de la fonction pour accéder à l’objet ou à d’autres objets accessibles grâce à la référence qu’on a fait passer. Par exemple, examinez la page HTML suivante : <html> <script src="ASLibrary.swf" type="application/x-shockwave-flash"></script> <script> num = 254; function getStatus() { return "OK."; Les langages JavaScript et ActionScript définissent tous deux les classes Date et RegExp, mais les objets de ces types ne sont pas automatiquement convertis d’un contexte d’exécution à l’autre. Vous devez d’abord convertir les objets Date et RegExp au type équivalent avant de les utiliser pour définir des propriétés ou des paramètres de fonction dans l’autre contexte d’exécution. Par exemple, le code ActionScript ci-dessous convertit un objet Date de JavaScript appelé jsDate en un objet Date ActionScript : var asDate:Date = new Date(jsDate.getMilliseconds());
RegExp d’ActionScript : var flags:String = ""; if (jsRegExp.dotAll) flags += "s"; if (jsRegExp.extended) flags += "x"; if (jsRegExp.global) flags += "g"; if (jsRegExp.ignoreCase) flags += "i"; if (jsRegExp.multiline) flags += "m"; var asRegExp:RegExp = new RegExp(jsRegExp.source, flags); Par exemple, examinez la page HTML simple suivante :
Dernière mise à jour le 27/4/2013
Le modèle de sécurité du moteur d’exécution isole le code de différentes origines. La programmation croisée du contenu dans des sandbox de sécurité distincts permet au contenu d’un sandbox de sécurité d’accéder à des propriétés et à des méthodes sélectionnées dans un autre.
Adobe AIR 1.0 et les versions ultérieures AIR applique une politique d’origine commune qui empêche le code d’un domaine d’interagir avec le contenu d’un autre. Tous les fichiers sont placés dans un sandbox sur la base de leur origine. Habituellement, le contenu d’un sandbox d’application ne peut pas enfreindre le principe d’origine commune et inter-coder le contenu chargé depuis un emplacement qui se trouve hors du répertoire d’installation de l’application. Toutefois, AIR met à votre disposition quelques techniques qui vous permettent d’inter-coder du contenu hors application. L’une d’entre elles utilise des images ou des iframes pour mapper le contenu de l’application dans un sandbox de sécurité distinct. Toute page chargée à partir de la zone à sandbox de l’application se comporte comme si elle l’avait été à partir du domaine distant. Par exemple, le mappage du contenu de l’application sur le domaine example.com lui permettrait d’inter-coder des pages chargées à partir d’example.com. Comme cette technique place le contenu de l’application dans un sandbox distinct, le code au sein de ce contenu n’est non plus assujetti aux restrictions qui entourent l’exécution du code des chaînes évaluées. Vous pouvez utiliser la technique de mappage des sandbox pour assouplir ces restrictions, même s’il n’est pas nécessaire d’inter-coder un contenu distant. Le mappage de contenu de cette façon est particulièrement utile lorsque vous travaillez avec l’une des nombreuses structures de JavaScript ou avec du code existant qui se fonde sur l’évaluation des chaînes. Toutefois, vous devriez tenir compte d’un risque supplémentaire et vous en prémunir : celui d’un contenu non approuvé qui pourrait être introduit et exécuté lorsque le contenu tourne hors du sandbox de l’application. Cependant, un contenu de l’application mappé sur un autre sandbox perd son droit d’accès à des interfaces de programmation d’AIR de telle sorte que la technique de mappage du sandbox ne peut pas être utilisée pour présenter des fonctionnalités d’AIR à du code exécuté hors du sandbox de l’application. Une autre technique de programmation croisée vous permet de créer une interface, appelée pont de sandbox, qui sert de passerelle entre le contenu d’un sandbox hors application et son document parent dans le sandbox de l’application. Le pont permet au contenu enfant d’accéder à des propriétés et à des méthodes définies par le parent et inversement, ou bien les deux à la fois. Enfin, vous pouvez lancer des XMLHttpRequests entre les domaines à partir du sandbox de l’application et, facultativement, d’autres sandbox. Pour plus d’informations, voir « Eléments image et iframe HTML » à la page 1011, « Sécurité HTML dans Adobe AIR » à la page 1127 et « Objet XMLHttpRequest » à la page 1005.
Pour permettre à un contenu de l’application d’inter-coder sans risque un contenu chargé à partir d’un emplacement se trouvant hors du répertoire d’installation de l’application, vous pouvez utiliser l’élément image ou iframe pour charger ce contenu en tant que contenu externe dans le même sandbox de sécurité. Si vous ne voulez pas inter-coder de contenu distant mais que vous souhaitez charger une page de votre application hors du sandbox de l’application, vous pouvez utiliser la même technique, c’est-à-dire spécifier http://localhost/ ou toute autre valeur inoffensive comme domaine d’origine. AIR ajoute les nouveaux attributs, sandboxRoot et documentRoot à l’élément d’image pour vous permettre de spécifier si un fichier d’application chargé dans l’image devrait être mappé sur un sandbox hors application. Les fichiers dont la résolution aboutit à un chemin sous l’URL sandboxRoot sont plutôt chargés à partir du répertoire documentRoot. Pour des raisons de sécurité, le contenu de l’application chargé ainsi est traité comme s’il avait été chargé à partir de l’URL de sandboxRoot. La propriété sandboxRoot spécifie l’URL à utiliser pour déterminer le sandbox et le domaine dans lesquels placer le contenu de l’image. Les modèles d’URL file:, http: ou https: doivent être utilisés. Si vous spécifiez une URL relative, le contenu reste dans le sandbox de l’application. La propriété documentRoot spécifie le répertoire à partir duquel il faut charger le contenu de l’image. Les modèles d’URL app:, http: ou app-storage: doivent être utilisés. L’exemple ci-dessous mappe le contenu installé dans le sous-répertoire sandbox de l’application qui doit s’exécuter dans le sandbox distant et le domaine www.example.com : <iframe src="http://www.example.com/local/ui.html" sandboxRoot="http://www.example.com/local/" documentRoot="app:/sandbox/"> </iframe>
Vous pouvez utiliser un pont de sandbox lorsqu’un contenu dans le sandbox de l’application doit accéder à des propriétés ou des méthodes définies par un contenu dans un sandbox hors application ou encore lorsqu’un contenu hors application doit accéder à des propriétés et des méthodes définies par un contenu dans le sandbox de l’application. Créez un pont avec les propriétés childSandboxBridge et parentSandboxBridge de l’objet window de tout document enfant.
Adobe AIR 1.0 et les versions ultérieures La propriété childSandboxBridge permet au document enfant de présenter une interface au contenu dans le document parent. Pour présenter une interface, vous définissez la propriété childSandbox sur une fonction ou un objet dans le document enfant. Vous pouvez alors accéder à l’objet ou la fonction à partir du contenu dans le document parent. L’exemple ci-dessous montre comment un script qui s’exécute dans un document enfant peut présenter un objet contenant une fonction ou une propriété à son parent : var interface = {}; interface.calculatePrice = function(){ return ".45 cents"; } interface.storeID = "abc" window.childSandboxBridge = interface;
//write text to file } document.getElementById("child").contentWindow.parentSandboxBridge = interface;
Pour qu’un script dans un document enfant accède à un pont de sandbox parent, le pont doit être paramétré avant l’exécution du script. Les objets fenêtre, image et iframe distribuent un événement dominitialize lorsqu’une page DOM est créée, mais avant qu’un script ne soit analysé ou des éléments DOM ajoutés. Vous pouvez utiliser l’événement dominitialize pour établir le pont suffisamment tôt dans la séquence de création de la page afin que tous les scripts du document enfant puissent y accéder. L’exemple ci-dessous montre comment créer un pont de sandbox parent en réponse à l’événement dominitialize distribué à partir de l’image enfant : <html> <head> <script> var bridgeInterface = {}; bridgeInterface.testProperty = "Bridge engaged"; function engageBridge(){ document.getElementById("sandbox").contentWindow.parentSandboxBridge = bridgeInterface; Dernière mise à jour le 27/4/2013
La classe HTMLHost définit un ensemble de comportements associés par défaut à un objet HTMLLoader. Lorsque vous créez un objet HTMLLoader, aucune mise en œuvre de HTMLHost n’est fournie. Ainsi, lorsque le contenu HTML déclenche l’un des comportements par défaut, comme un changement d’emplacement de la fenêtre ou du titre de la fenêtre, rien ne se passe. Vous pouvez étendre la classe HTMLHost pour définir les comportements souhaités pour votre application. Une mise en œuvre par défaut du HTMLHost est fournie pour les fenêtres créées par AIR. Vous pouvez affecter la mise en œuvre de HTMLHost par défaut à un autre objet HTMLLoader en paramétrant la propriété htmlHost de l’objet à l’aide d’un nouvel objet HTMLHost créé avec le paramètre defaultBehavior défini sur true. Remarque : dans Adobe® Flex™ Framework, l’objet HTMLLoader est encadré par le composant mx:HTML. Lorsque vous utilisez Flex, faites appel au composant HTML.
Adobe AIR 1.0 et les versions ultérieures Un objet HTMLLoader hérite des propriétés d’affichage de la classe Adobe® Flash® Player Sprite. Vous pouvez redimensionner, déplacer, masquer et changer la couleur d’arrière-plan, par exemple. Ou vous pouvez appliquer des effets avancés comme les filtres, les masques, les mises à l’échelle et la rotation. Lorsque vous appliquez des effets, évaluez l’impact sur la lisibilité. Les contenus SWF et PDF chargés dans une page HTML ne peuvent pas s’afficher lorsque certains effets sont appliqués. Les fenêtres HTML contiennent un objet HTMLLoader qui restitue le contenu HTML. L’objet est limité à la zone de la fenêtre de sorte qu’un changement dans les dimensions, la position, la rotation ou l’échelle ne produit pas toujours les résultats escomptés.
Adobe AIR 1.0 et les versions ultérieures Les propriétés d’affichage de base de HTMLLoader vous permettent de positionner le contrôle au sein de l’objet d’affichage parent, de définir la taille et d’afficher ou masquer le contrôle. Vous ne devriez pas changer ces objets pour l’objet HTMLLoader d’une fenêtre HTML. Les propriétés de base contiennent :
Programmation du conteneur HTML d’AIR à l’aide de scripts
Lors du chargement de contenu dans un nouvel objet HTMLLoader (la propriété width est toujours définie sur 0), il peut être tentant de définir les paramètres width et height du HTMLLoader à l’aide des propriétés contentWidth et contentHeight. Cette technique est valable pour les pages qui disposent d’une largeur minimale raisonnable lorsqu’elles sont déployées selon les règles de HTML et du flux CSS. Toutefois, en l’absence d’une largeur raisonnable fournie par le HTMLLoader, certaines pages sont intégrées en une mise en page longue et étroite. Remarque : lorsque vous changez la largeur et la hauteur de l’objet HTMLLoader, les valeurs scaleX et scaleY ne changent pas, comme ce serait le cas avec la plupart des autres objets d’affichage.
Adobe AIR 1.0 et les versions ultérieures La propriété paintsDefaultBackground d’un objet HTMLLoader, qui est true par défaut, détermine si l’objet HTMLLoader dessine un arrière-plan opaque. Lorsque paintsDefaultBackground est false, l’arrière-plan est clair. Le conteneur de l’objet d’affichage ou les autres objets d’affichage en dessous de l’objet HTMLLoader sont visibles derrière les éléments de premier plan du contenu HTML. Si l’élément de corps ou tout autre élément du document HTML spécifie une couleur d’arrière-plan, à l’aide de style="background-color:gray", par exemple, l’arrière-plan de cette portion de HTML est alors opaque et
HTMLLoader et paintsDefaultBackground est false, la couleur définie pour le opaqueBackground est alors visible. Remarque : vous pouvez utiliser une illustration transparente et au format PNG pour fournir un arrière-plan semitransparent à un élément dans un document HTML. La définition du style d’opacité d’un élément HTML n’est pas prise en charge.
Adobe AIR 1.0 et les versions ultérieures Evitez la mise à l’échelle d’un objet HTMLLoader au delà d’un facteur 1.0. Le texte d’un contenu HTMLLoader est restitué à une résolution spécifique et il apparaît pixelisé si l’échelle de l’objet HTMLLoader est augmentée. Pour éviter que le HTMLLoader, ainsi que son contenu, ne soit redimensionné lorsqu’une fenêtre l’est, définissez la propriété scaleMode de la scène sur StageScaleMode.NO_SCALE.
Le contenu SWF ou PDF chargé dans un objet HTMLLoader disparaît dans les conditions suivantes :
• Si vous attribuez à la propriété alpha de l’objet HTMLLoader une valeur autre que 1.0. • Si vous faites pivoter le contenu HTMLLoader. Le contenu réapparaît si vous retirez le paramétrage de la propriété fautive et supprimez les filtres actifs. Par ailleurs, le moteur d’exécution ne peut pas afficher de contenu PDF dans une fenêtre transparente. Il n’affiche le contenu SWF intégré à une page HTML que si le paramètre wmode de l’objet ou de la balise embed est défini sur opaque ou transparent. Puisque la valeur par défaut de wmode est window, le contenu SWF ne s’affiche pas dans une fenêtre transparente, sauf si vous définissez explicitement le paramètre wmode. Remarque : dans les versions d’AIR antérieures à 1.5.2, le contenu SWF intégré à HTML ne s’affichait pas, quelle que soit la valeur wmode définie. Pour plus d’informations sur le chargement de ces types de média dans un objet HTMLLoader, voir les sections « Intégration d’un contenu SWF en HTML » à la page 1031 et « Ajout d’un contenu PDF dans AIR » à la page 569.
Adobe AIR 1.0 et les versions ultérieures La classe HTMLLoader hérite de plusieurs méthodes qui peuvent être utilisées pour des effets spéciaux. En règle générale, ces effets ont des limites lorsqu’ils sont utilisés avec l’affichage du HTMLLoader, mais ils peuvent être utiles pour les transitions ou autres effets temporaires. Par exemple, si vous affichez une fenêtre de dialogue pour rassembler les saisies de l’utilisateur, vous pourriez flouter l’affichage de la fenêtre principale jusqu’à ce que celui-ci mette fin au dialogue. De même, vous pourriez faire un fondu lors de la fermeture de la fenêtre Les propriétés d’affichage avancées sont les suivantes : Propriété
Dernière mise à jour le 27/4/2013
Accès à l’historique de HTML Adobe AIR 1.0 et les versions ultérieures A mesure que de nouvelles pages sont chargées dans un objet HTMLLoader, le moteur d’exécution actualise un historique pour l’objet. L’historique correspond à l’objet window.history dans la page HTML. La classe HTMLLoader contient les méthodes et propriétés suivantes qui vous permettent d’utiliser l’historique de HTML : Membre de la classe
La classe HTMLLoader possède une propriété userAgent qui vous permet de définir la chaîne de l’agent d’utilisateur employé par HTMLLoader. Paramétrez la propriété userAgent de l’objet HTMLLoader avant d’appeler la méthode load(). Si vous définissez cette propriété sur l’occurrence de HTMLLoader, la propriété userAgent de l’URLRequest transmise à la méthode load() n’est alors pas utilisée. Vous pouvez définir la chaîne de l’agent d’utilisateur employée par tous les objets HTMLLoader dans un domaine d’application en paramétrant la propriété URLRequestDefaults.userAgent. Les propriétés URLRequestDefaults statiques sont appliquées par défaut à tous les objets URLRequest, et pas seulement aux objets URLRequest utilisés avec la méthode load() des objets HTMLLoader. Le paramétrage de la propriété userAgent d’un HTMLLoader remplace celui par défaut de URLRequestDefaults.userAgent. Si vous ne paramétrez pas une valeur de l’agent d’utilisateur pour la propriété userAgent de l’objet HTMLLoader ou pour URLRequestDefaults.userAgent, la valeur de l’agent d’utilisateur AIR par défaut est employée. Cette valeur par défaut varie suivant le système d’exploitation utilisé à l’exécution (Mac OS ou Windows, par exemple), le langage du moteur d’exécution et sa version, comme dans les deux exemples suivants :
Paramétrez l’une ou l’autre de ces propriétés avant le chargement du contenu HTML.
JavaScript propose plusieurs interfaces de programmation pour contrôler la fenêtre qui affiche le contenu HTML. Dans AIR, vous pouvez annuler ces API en implémentant une classe HTMLHost personnalisée.
Adobe AIR 1.0 et les versions ultérieures Si, par exemple, votre application présente plusieurs objets HTMLLoader dans une interface à onglets, vous pourriez souhaiter changer le libellé d’un onglet à l’aide des pages HTML chargées, sans toucher au titre de la fenêtre principale. De même, votre code pourrait répondre à un appel window.moveTo() en repositionnant l’objet HTMLLoader dans son conteneur d’objet d’affichage parent, en déplaçant la fenêtre qui contient l’objet HTMLLoader, en ne faisant rien du tout ou en faisant tout autre chose. La classe HTMLHost d’AIR contrôle les méthodes et propriétés JavaScript suivantes :
HTMLLoader, une occurrence de HTMLHost qui prend en charge les comportements est automatiquement affectée. Vous pouvez changer le comportement de l’objet hôte en affectant une implémentation HTMLLoader différente à la propriété htmlHost du HTMLLoader ou bien vous pouvez affecter null pour désactiver complètement les fonctions. Remarque : AIR affecte un objet HTMLHost par défaut à la fenêtre initiale créée pour une application AIR à base d’HTML et à toute fenêtre créée par l’implémentation par défaut de la méthode window.open()) JavaScript.
Adobe AIR 1.0 et les versions ultérieures L’exemple ci-dessous montre comment personnaliser l’affectation de l’interface utilisateur par un objet HTMLLoader en étendant la classe HTMLLoader : Exemple Flex : 1 Créez une classe qui étend la classe HTMLHost (une sous-classe). 2 Remplacez les méthodes de la nouvelle classe pour gérer les changements dans les paramètres de l’utilisateur liés à
àwindow.open() et les changements à window.document.title. Les appels à window.open() ouvrent la page HTML dans une nouvelle fenêtre et les changements à window.document.title, y compris le paramétrage de l’élément <title> d’une page HTML, définissent le titre de cette fenêtre.
Dernière mise à jour le 27/4/2013
Remplacez la méthode locationChange() pour traiter les changements apportés à l’URL de la page HTML. La méthode locationChange() est appelée lorsque JavaScript dans une page change la valeur de window.location. L’exemple ci-dessous charge tout simplement l’URL demandée : override public function updateLocation(locationURL:String):void { htmlLoader.load(new URLRequest(locationURL)); } Adobe AIR 1.0 et les versions ultérieures Remplacez la méthode createWindow() pour traiter les appels JavaScript à window.open(). Les implémentations de la méthode createWindow() sont responsables de la création d’un objet HTMLLoader et de son renvoi. Vous afficheriez généralement le HTMLLoader dans une nouvelle fenêtre, mais la création d’une fenêtre n’est pas nécessaire. L’exemple suivant décrit comment implémenter la fonction createWindow() à l’aide du HTMLLoader.createRootWindow() pour créer à la fois la fenêtre et l’objet HTMLLoader. Vous pouvez aussi créer un objet NativeWindow à part et ajouter le HTMLLoader à la scène de la fenêtre. override public function createWindow(windowCreateOptions:HTMLWindowCreateOptions):HTMLLoader{ var initOptions:NativeWindowInitOptions = new NativeWindowInitOptions(); var bounds:Rectangle = new Rectangle(windowCreateOptions.x, windowCreateOptions.y, windowCreateOptions.width, windowCreateOptions.height); var htmlControl:HTMLLoader = HTMLLoader.createRootWindow(true, initOptions, windowCreateOptions.scrollBarsVisible, bounds); htmlControl.htmlHost = new HTMLHostImplementation(); if(windowCreateOptions.fullscreen){ htmlControl.stage.displayState = StageDisplayState.FULL_SCREEN_INTERACTIVE; } return htmlControl; }
Propriété HTMLWindowCreateOptions
Votre application doit fournir des barres de défilement, des barres d’adresses, des barres de menus, des barres d’état et des barres d’outils lorsque cela convient. Les autres arguments pour la méthode window.open() de JavaScript sont traités par le système. Une implémentation createWindow() ne devrait pas charger de contenu dans l’objet HTMLLoader ou définir le titre de la fenêtre.
Adobe AIR 1.0 et les versions ultérieures Remplacez window.close() pour que les appels JavaScript soient traités par la méthode window.close(). L’exemple ci-dessous ferme la fenêtre de l’ordinateur de bureau lorsque la méthode window.close() est appelée : override public function windowClose():void { htmlLoader.stage.nativeWindow.close(); }
Remplacez la méthode updateStatus() pour traiter les changements JavaScript à la valeur de window.status. L’exemple ci-dessous assure le suivi de la valeur d’état : override public function updateStatus(status:String):void { trace(status); }
L’objet HTMLLoader ne fournit pas de barre d’état.
Adobe AIR 1.0 et les versions ultérieures Remplacez la méthode updateTitle() pour traiter les changements JavaScript à la valeur de window.document.title. L’exemple ci-dessous change le titre de la fenêtre et ajoute la chaîne "Sample" au titre : override public function updateTitle(title:String):void { htmlLoader.stage.nativeWindow.title = title + " - Sample"; }
Il n’est pas nécessaire que les changements à document.titlemodifient le titre de la fenêtre contenant l’objet HTMLLoader. Vous pourriez, par exemple, changer un autre élément d’interface, tel qu’un champ de texte.
Adobe AIR 1.0 et les versions ultérieures Remplacez les méthodes windowBlur() et windowFocus() pour traiter les appels JavaScript à window.blur() et window.focus(), comme le montre l’exemple ci-dessous : override public function windowBlur():void { htmlLoader.alpha = 0.5; } override public function windowFocus():void { htmlLoader.alpha = 1.0; La classe HTMLLoader inclut une méthode statique, HTMLLoader.createRootWindow(), vous permettant d’ouvrir une nouvelle fenêtre (représentée par un objet NativeWindow) qui contient un object HTMLLoader et qui définit quelques paramètres d’interface utilisateur pour cette fenêtre. Il faut à cette méthode quatre paramètres pour vous permettre de définir l’interface utilisateur. Paramètre
Dernière mise à jour le 27/4/2013
Toutefois, si vous appelez createRootWindow() indirectement en remplaçant la méthode HTMLHost createWindow() pour appeler createRootWindow(), opener et parent font effectivement référence à la fenêtre HTML d’ouverture.
Adobe AIR 1.0 et les versions ultérieures Vous pouvez créer une sous-classe de la classe HTMLLoader pour créer des comportements. Par exemple, vous pouvez créer une sous-classe qui définisse des écouteurs d’événement par défaut pour les événements HTMLLoader, tels que ces événements distribués lorsque HTML est restitué ou que l’utilisateur clique sur un lien. L’exemple suivant étend la classe HTMLHost pour fournir un comportement normal lorsque la méthode window.open() JavaScript est appelée. L’exemple définit alors une sous-classe de HTMLLoader qui utilise la classe d’implémentation du HTMLHost personnalisé : package { import flash.html.HTMLLoader; public class MyHTMLHost extends HTMLHost { public function MyHTMLHost() { super(false); événements système de manière pratique. Le modèle d’événement Adobe® AIR® n’est pas seulement utile, il est également conforme aux standards en vigueur. 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 un outil puissant, mais parfaitement intuitif.
Adobe AIR 1.0 et les versions ultérieures Un objet HTMLLoader déclenche les événements Adobe® ActionScript® 3.0 suivants : Si un lien est ouvert dans le navigateur système, aucun événement locationChanging n’est distribué, car l’objet HTMLLoader ne change pas d’emplacement.
événement scroll résulte d’un accès aux liens d’ancrage (liens #) sur la page ou d’un appel de la méthode window.scrollTo(). La saisie de texte dans une zone de texte ou d’entrée de texte peut également provoquer un événement scroll.
Dernière mise à jour le 27/4/2013
Adobe AIR 1.0 et les versions ultérieures Vous pouvez enregistrer des fonctions ActionScript qui répondent à des événements JavaScript. Examinons par exemple le contenu HTML suivant : <html> <body> <a href="#" id="testLink">Click me.</a> événements. Il est par exemple possible de remplacer la méthode completeHandler() dans l’exemple précédent par le code suivant : function completeHandler(event:Event):void { var testLink:Object = html.window.document.getElementById("testLink"); testLink.addEventListener("click", clickHandler); }
Les classes d’exécution gèrent l’ajout de gestionnaires d’événement à l’aide de la méthode addEventListener(). Pour ajouter une fonction de gestionnaire associée à un événement, appelez la méthode addEventListener() de l’objet qui distribue l’événement en indiquant le type d’événement et la fonction concernée. Par exemple, pour écouter l’événement closing distribué lorsqu’un utilisateur clique sur le bouton de fermeture de fenêtre dans la barre de titre, utilisez l’instruction suivante : window.nativeWindow.addEventListener(air.NativeWindow.CLOSING, handleWindowClosing);
Le code suivant crée un fichier HTML simple qui affiche des informations sur la position de la fenêtre principale. Une fonction de gestionnaire appelée moveHandler() écoute un événement move (défini par la classe NativeWindowBoundsEvent) de la fenêtre principale. <html> <script src="AIRAliases.js" /> <script> function init() { writeValues(); window.nativeWindow.addEventListener(air.NativeWindowBoundsEvent.MOVE, moveHandler); Adobe AIR 1.0 et les versions ultérieures 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().
Lorsqu’un contenu HTML navigue ou qu’il est éliminé parce qu’une fenêtre dans laquelle il figure est fermée, les écouteurs d’événement qui font référence aux objets sur la page déchargée ne sont pas automatiquement supprimés. Lorsqu’un objet distribue un événement à un gestionnaire qui a déjà été déchargé, le message d’erreur suivant s’affiche : « The application attempted to reference a JavaScript object in an HTML page that is no longer loaded » (L’application a tenté de référencer un objet JavaScript sur une page HTML qui n’est plus chargée). Pour éviter que ce message d’erreur ne s’affiche, supprimez les écouteurs d’événement JavaScript intégrés à une page HTML avant qu’elle ne soit déchargée. En cas de navigation de page (au sein d’un objet HTMLLoader), supprimez l’écouteur d’événement lors de l’événement unload de l’objet window. Par exemple, le code JavaScript suivant supprime un écouteur associé à un événement uncaughtScriptException : window.onunload = cleanup; window.htmlLoader.addEventListener('uncaughtScriptException', uncaughtScriptException); function cleanup() { window.htmlLoader.removeEventListener('uncaughtScriptException', uncaughtScriptExceptionHandler); } La méthode hasEventListener() vous permet de vérifier l’existence d’un écouteur d’événement associé à un objet.
StageWebView.isSupported pour déterminer si la classe est prise en charge sur le périphérique en cours. Le profil mobile n’assure pas la prise en charge de tous les périphériques. Dans tous les profils, la classe StageWebView ne prend en charge qu’une interaction restreinte entre le contenu HTML et le reste de l’application. Vous pouvez contrôler la navigation, mais l’intercodage ou les échanges directs de données sont interdits. Vous pouvez charger un contenu à partir d’une URL locale ou distante ou transmettre une chaîne de contenu HTML.
Un objet StageWebView n’est pas un objet d’affichage et il est impossible de l’ajouter à la liste d’affichage. Il fait plutôt office de fenêtre d’affichage directement associée à la scène. Un contenu StageWebView est superposé à n’importe quel contenu de liste d’affichage. Il n’existe aucun moyen de contrôler l’ordre de tracé de plusieurs objets StageWebView. Pour afficher un objet StageWebView, vous affectez la scène sur laquelle il doit apparaître à sa propriété stage. Définissez la taille de l’affichage à l’aide de la propriété viewPort. Définissez les coordonnées x et y de la propriété viewPort sur une valeur comprise entre -8192 et 8191. La largeur et la hauteur maximales de la scène ne doivent pas dépasser 8191. Si la taille excède les valeurs maximales, une exception est renvoyée. L’exemple suivant crée un objet StageWebView, définit les propriétés stage et viewPort et affiche une chaîne de contenu HTML : var webView:StageWebView = new StageWebView(); webView.viewPort = new Rectangle( 0, 0, this.stage.stageWidth, this .stage.stageHeight); webView.stage = this.stage; var htmlString:String = "<!DOCTYPE HTML>" + "<html><body>" + "<p>King Philip could order five good steaks.</p>" + "</body></html>"; webView.loadString( htmlString ); Vous disposez de deux méthodes, loadURL() et loadString(), pour charger un contenu dans un objet StageWebView. La méthode loadURL() charge une ressource à l’adresse URL indiquée. Libre à vous de faire appel à tout modèle d’URI pris en charge par le contrôle du navigateur Web du système, tel que data:, file:, http:, https: et javascript:. Les modèles app: et app-storage: ne sont pas pris en charge. AIR ne valide pas la chaîne URL. La méthode loadString() charge une chaîne littérale qui intègre un contenu HTML. L’emplacement d’une page chargée par le biais de cette méthode est exprimé comme suit :
• Sur iOS : htmlString • Sur Android : format URI de données de l’élément htmlString codé Le modèle d’URI détermine les règles de chargement de contenu ou de données intégrés.
L’exemple suivant fait appel à l’objet StageWebView pour afficher le site Web d’Adobe : package { import flash.display.MovieClip; import flash.media.StageWebView; import flash.geom.Rectangle; public class StageWebViewExample extends MovieClip{ var webView:StageWebView = new StageWebView(); public function StageWebViewExample() { webView.stage = this.stage; webView.viewPort = new Rectangle( 0, 0, stage.stageWidth, stage.stageHeight ); webView.loadURL( "http://www.adobe.com" ); } } Activation de Flash Player et d’autres modules d’extension dans un objet StageWebView.
Vous disposez d’un URI JavaScript pour appeler une fonction définie sur la page HTML chargée par un objet StageWebView. La fonction appelée par le biais de l’URI JavaScript s’exécute dans le contexte de la page Web chargée. L’exemple suivant appelle une fonction JavaScript à l’aide d’un objet StageWebView : package { import flash.display.*; import flash.geom.Rectangle; import flash.media.StageWebView; public class WebView extends Sprite { public var webView:StageWebView = new StageWebView(); public function WebView() { var htmlString:String = "<!DOCTYPE HTML>" + "<html><script type=text/javascript>" + Un événement locationChanging est distribué lors de chaque redirection HTML. Les événements locationChange et complete sont distribués au moment opportun. Sur iOS, un événement locationChanging est distribué avant un événement locationChange, à l’exception des premières méthodes loadURL() ou loadString(). La distribution d’un événement locationChange est également associée aux changements de navigation via des iFrames et images.
Lorsque l’objet StageWebView cesse d’être la cible d’action, il distribue un événement focusOut. Une occurrence de l’objet StageWebView peut cesser d’être la cible d’action lorsqu’un utilisateur « évite » le premier ou le dernier contrôle de la page Web à l’aide des touches de direction ou d’un trackball (boule roulante) de périphérique. La propriété direction de l’objet d’événement permet de savoir si la cible d’action remonte au-delà du haut de la page ou descend via le bas de la page. Grâce à ces informations, vous pouvez faire de l’objet d’affichage approprié placé au-dessus ou au-dessous de l’objet StageWebView la cible d’action.
événements focusIn et focusOut en définissant la propriété de direction de FocusEvent sur none. Si l’utilisateur touche l’intérieur de l’objet StageWebView, l’événement focusIn est distribué. Si l’utilisateur touche l’extérieur de l’objet StageWebView, l’événement focusOut est distribué. L’exemple suivant illustre la transition de la cible d’action de l’objet StageWebView aux objets d’affichage Flash : package { import import import import import import import import import import
Grâce aux programmes de travail ActionScript, il est possible d’exécuter du code simultanément, c’est-à-dire d’exécuter du code en arrière-plan sans interrompre l’exécution du code principal. Les API de simultanéité d’ActionScript sont disponibles sur les plates-formes de bureau uniquement dans Flash Player 11.4 et les versions ultérieures et dans AIR 3.4 et les versions ultérieures. La simultanéité n’est pas prise en charge dans AIR sur les plates-formes mobiles.
Flash Player 11.4 et les versions ultérieures, Adobe AIR 13.4 et les versions ultérieures pour les plates-formes de bureau Lorsqu’une application n’utilise pas des programmes de travail, son code s’exécute dans un bloc d’exécution linéaire unique appelé thread d’exécution. Ce thread exécute le code écrit par un développeur. Il exécute également une grande partie du code appartenant au moteur d’exécution, plus particulièrement le code qui met à jour l’écran lorsque les propriétés des objets d’affichage changent. Bien que le code soit écrit par blocs en tant que méthodes et classes, il s’exécute ligne par ligne au moment de l’exécution même s’il a été écrit dans une longue série d’étapes. Supposons qu’une application exécute les étapes suivantes : 1 Image d’entrée : le moteur d’exécution appelle des gestionnaires d’événement enterFrame et exécute tour à tour
2 Evénement de souris : l’utilisateur déplace la souris, et le moteur d’exécution appelle les gestionnaires d’événements
3 Evénement de fin de chargement : une demande de chargement d’un fichier xml provenant d’une URL est renvoyée
4 Evénement de souris : la souris s’est à nouveau déplacée ; le moteur d’exécution appelle donc les gestionnaires
5 Rendu : plus aucun événement n’est en attente ; le moteur d’exécution met donc à jour l’écran en fonction des
6 Image d’entrée : le cycle recommence.
Utilisation de programmes de travail à des fins de simultanéité
Supposez néanmoins que les données xml qui se chargent à l’étape 3 représentent une très grande structure xml profondément imbriquée. Etant donné que le code s’exécute en boucle sur les données xml et crée des objets, il est tout à fait possible que cette opération prenne plus d’un trentième de seconde. Dans ce cas, les dernières étapes (répondre à la souris et actualiser l’écran) ne sont pas exécutées au moment où elles le devraient. Résultat : l’écran se bloque, car il n’est pas actualisé assez vite en réponse à l’utilisateur qui déplace la souris. Si l’ensemble du code s’exécute dans le même thread, il n’existe qu’un seul moyen d’éviter les blocages occasionnels : éviter les opérations longues telles que l’exécution en boucle sur un jeu de données volumineux. Les programmes de travail d’ActionScript proposent une solution alternative. Un programme de travail peut vous permettre d’exécuter du code à exécution longue dans un programme de travail indépendant. Comme chaque programme de travail est exécuté dans un thread différent, le programme de travail en arrière-plan lance l’opération longue dans son propre thread. Cela évite ainsi au thread d’exécution du programme de travail principal d’actualiser l’écran à chaque image et d’être bloqué par un autre processus. La possibilité d’exécuter plusieurs opérations de code en même temps de cette manière est appelée simultanéité. Lorsque le programme de travail en arrière-plan finit son travail, ou à certaines étapes-clés du processus, vous pouvez envoyer au programme de travail principal des notifications et des données. De cette manière, vous pouvez écrire du code qui exécute des opérations longues ou complexes tout en évitant le blocage de l’écran. Les programmes de travail sont utiles, car ils diminuent le risque d’une baisse de la cadence, qui peut se produire si le thread de rendu principal est bloqué par l’exécution d’un autre code. Les programmes de travail augmentent toutefois l’utilisation de la mémoire système et du processeur, ce qui peut avoir une incidence considérable sur les performances globales de l’application. Etant donné que chaque programme de travail utilise sa propre occurrence de la machine virtuelle du moteur d’exécution, le traitement d’un programme de travail, aussi simple soit-il, peut consommer de nombreuses ressources. Lorsque vous utilisez des programmes de travail, testez votre code sur toutes vos plates-formes cibles afin de vous assurer que les ressources requises ne sont pas trop importantes. Adobe vous recommande de ne pas utiliser plus de deux programmes de travail dans un scénario type.
Flash Player 11.4 et les versions ultérieures, Adobe AIR 13.4 et les versions ultérieures pour les plates-formes de bureau La première étape pour utiliser un programme de travail à des fins de simultanéité est de créer un programme de travail en arrière-plan. Vous devez utiliser deux types d’objets pour créer un programme de travail. Une occurrence de l’objet Worker, que vous créez. Un objet WorkerDomain, qui crée le programme de travail et gère les objets Worker qui s’exécutent dans une application. Lorsque le moteur d’exécution se charge, il crée l’objet WorkerDomain. Par ailleurs, le moteur d’exécution crée automatiquement un programme de travail pour le fichier swf de l’application. Ce premier programme de travail est appelé programme de travail primordial. Etant donné qu’il n’existe qu’un seul objet WorkerDomain pour une application, vous accédez à l’occurrence de l’objet WorkerDomain à l’aide de la propriété statique WorkerDomain.current.
Vous pouvez à tout moment accéder à l’occurrence de l’objet Worker actuel (le programme de travail dans lequel le code actuel s’exécute) à l’aide de la propriété statique Worker.current.
Tout comme le fichier swf principal qui s’exécute au sein du programme de travail primordial, un programme de travail en arrière-plan exécute le code d’un seul fichier swf. Pour utiliser un programme de travail en arrière-plan, vous devez créer et compiler le code du programme de travail dans un fichier swf. Pour créer le programme de travail en arrière-plan, le programme de travail parent doit accéder aux octets de ce fichier swf en tant qu’objet ByteArray. Vous devez transmettre cet objet ByteArray à la méthode createWorker() de l’objet WorkerDomain pour créer le programme de travail. Il existe trois méthodes principales pour convertir le fichier swf de programme de travail en arrière-plan en objet ByteArray :
Utilisez la métabalise [Embed] pour intégrer le fichier swf de programme de travail dans le fichier swf principal sous forme d’objet ByteArray : [Embed(source="../swfs/BgWorker.swf", mimeType="application/octet-stream")] private static var BgWorker_ByteClass:Class; private function createWorker():void { var workerBytes:ByteArray = new BgWorker_ByteClass(); var bgWorker:Worker = WorkerDomain.current.createWorker(workerBytes); // ... set up worker communication and start the worker Vous pouvez utiliser un seul fichier swf comme fichier swf principal et fichier swf de programme de travail. Utilisez la propriété loaderInfo.bytes de la classe d’affichage principale pour accéder aux octets du fichier swf. // The primordial worker's main class constructor public function PrimordialWorkerClass() { init(); } private function init():void Une fois le programme de travail créé, lancez l’exécution de son code en appelant la méthode start() de l’objet Worker. L’opération start() ne commence pas immédiatement. Pour savoir quand le programme de travail est exécuté, enregistrez un écouteur pour l’événement workerState de l’objet Worker. Cet événement est distribué lorsque l’objet Worker change d’état au cours de son cycle de vie, notamment lorsqu’il commence à exécuter le code. Dans votre gestionnaire d’événement workerState, vérifiez que la propriété state de l’objet Worker est définie sur WorkerState.RUNNING. A ce stade, le programme de travail est en cours d’exécution et le constructeur de sa classe principale s’est exécuté. Consultez la liste de code suivante pour obtenir un exemple d’enregistrement de l’événement workerState et d’appel de la méthode start() :
Si vous n’avez plus besoin d’un programme de travail, vous pouvez appeler la méthode terminate() de l’objet Worker pour arrêter le programme de travail et libérer sa mémoire, ainsi que les autres ressources du système.
Flash Player 11.4 et les versions ultérieures, Adobe AIR 13.4 et les versions ultérieures pour les plates-formes de bureau Bien que les programmes de travail exécutent leur code dans des threads d’exécution distincts, ils n’auraient aucun intérêt s’ils étaient totalement isolés les uns des autres. La communication entre les programmes de travail signifie principalement échanger des données. Il existe trois mécanismes principaux pour transmettre des données d’un programme de travail à un autre. Au moment de choisir la technique de partage la mieux adaptée à vos besoins de transmission de données, tenez compte des éléments qui les différencient. La première différence entre ces techniques est de savoir s’il existe un événement informant le récepteur que de nouvelles données sont disponibles ou si le programme de travail de réception doit rechercher les mises à jour. La deuxième différence entre ces techniques de partage de données porte sur la méthode de transmission des données. Dans certains cas, le programme de travail de réception obtient une copie des données partagées, ce qui implique la création de davantage d’objets, et donc une plus grande utilisation de la mémoire et du processeur. Dans d’autres cas, les programmes de travail accèdent aux objets faisant référence à la même mémoire système sous-jacente, ce qui implique la création de moins d’objets, et donc une plus faible utilisation de la mémoire. Ces différences sont précisées ici :
Technique de communication
Chaque programme de travail conserve un dictionnaire interne de valeurs de propriété partagée. Pour distinguer les propriétés entre elles, celles-ci sont enregistrées avec des noms de clés de type chaîne. Pour enregistrer un objet sur un programme de travail en tant que propriété partagée, appelez la méthode setSharedProperty() de l’objet Worker avec deux arguments, le nom de clé et la valeur à enregistrer : // code running in the parent worker bgWorker.setSharedProperty("sharedPropertyName", someObject);
// code running in the background worker receivedProperty = Worker.current.getSharedProperty("sharedPropertyName"); Pratiquement tout type d’objet peut être transmis comme valeur à la méthode setSharedProperty(). Lorsque vous appelez la méthode getSharedProperty(), l’objet renvoyé est une copie de l’objet transmis à la méthode setSharedProperty() et non une référence au même objet, sauf dans quelques cas isolés. La méthode de partage des données est expliquée en détails à la section « Références partagées et valeurs copiées » à la page 1083. Le principal avantage d’utiliser une propriété partagée pour transmettre des données entre programmes de travail est que celle-ci est disponible même avant que le programme de travail ne commence à s’exécuter. Vous pouvez appeler la méthode setSharedProperty() d’un objet de programme de travail en arrière-plan pour définir une propriété partagée, même avant que le programme de travail ne commence à s’exécuter. Lorsque le programme de travail parent appelle la méthode start() de l’objet Worker, le moteur d’exécution appelle le constructeur de la classe principale du programme de travail enfant. Toutes les propriétés partagées définies avant l’appel de la méthode start() sont disponibles dans le code afin que le programme de travail enfant puisse les lire.
Utilisation de programmes de travail à des fins de simultanéité
Un canal de message fournit un lien de transmission de données unidirectionnel entre deux programmes de travail. L’utilisation d’un objet MessageChannel pour transmettre des données entre programmes de travail présente un avantage majeur. Lorsque vous envoyez un message (un objet) à l’aide d’un canal de message, l’objet MessageChannel distribue un événement channelMessage. Le code dans le programme de travail de réception peut écouter cet événement pour savoir quand les données seront disponibles. De cette façon, le programme de travail de réception n’a pas besoin de rechercher continuellement des mises à jour de données. Un canal de message est associé à deux programmes de travail uniquement : un programme de travail d’envoi et un programme de travail de réception. Pour créer un objet MessageChannel, appelez la méthode createMessageChannel() de l’objet Worker d’envoi, en transmettant le programme de travail de réception en tant qu’argument : // In the sending worker swf var sendChannel:MessageChannel; sendChannel = Worker.current.createMessageChannel(receivingWorker);
MessageChannel. Cet événement est distribué lorsque le programme de travail d’envoi envoie les données via le canal de message. // In the receiving worker swf var incomingChannel:MessageChannel; incomingChannel = Worker.current.getSharedProperty("incomingChannel"); incomingChannel.addEventListener(Event.CHANNEL_MESSAGE, handleIncomingMessage);
// In the sending worker swf sendChannel.send("This is a message"); Le programme de travail de réception peut alors obtenir les données en appelant la méthode receive() de l’objet MessageChannel. private function handleIncomingMessage(event:Event):void { var message:String = incomingChannel.receive() as String; } Partage de données avec un objet ByteArray partageable Lors de la transmission d’un objet entre deux programmes de travail, le programme de travail de réception obtient un nouvel objet, qui est une copie de l’objet original. Ces deux objets sont stockés à divers emplacements dans la mémoire du système. Chaque copie de l’objet qui est reçue augmente donc la mémoire totale utilisée par le moteur d’exécution. Par ailleurs, les modifications apportées à un objet dans un programme de travail ne sont pas appliquées à la copie dans l’autre programme de travail. Pour plus d’informations sur la méthode de copie des objets, voir « Références partagées et valeurs copiées » à la page 1083. Par défaut, un objet ByteArray se comporte de la même façon. Si vous transmettez une occurrence de ByteArray à la méthode setSharedProperty() de l’objet Worker ou à la méthode send() de l’objet MessageChannel, le moteur d’exécution crée un nouvel objet ByteArray dans la mémoire de l’ordinateur et le programme de travail de réception obtient une occurrence de ByteArray qui est une référence au nouvel objet ByteArray. Vous pouvez néanmoins changer ce comportement pour un objet ByteArray en définissant sa propriété shareable sur true. Lorsqu’un objet ByteArray partageable est transmis d’un programme de travail à un autre, l’occurrence de ByteArray dans le programme de travail de réception est une référence à la même mémoire système sous-jacente utilisée par l’occurrence de ByteArray dans le programme de travail d’envoi. Lorsque le code d’un programme de travail modifie le contenu du tableau d’octets, ces modifications sont immédiatement disponibles dans d’autres programmes de travail ayant accès à ce tableau d’octets partagé. Etant donné que les programmes de travail exécutent leur code simultanément, deux programmes de travail peuvent tenter d’accéder en même temps aux mêmes octets dans un tableau d’octets, ce qui pourrait entraîner la perte ou la corruption des données. Vous pouvez utiliser plusieurs API pour gérer l’accès aux ressources partagées et éviter ces problèmes. La classe ByteArray dispose de méthodes vous permettant de valider et de modifier le contenu du tableau d’octets en une seule opération :
• Méthode atomicCompareAndSwapLength() En outre, le package flash.concurrent inclut des classes qui permettent de contrôler l’accès aux ressources partagées : • L’objet créé dans le programme de travail de réception lors de l’appel de sa méthode getSharedProperty() est désérialisé des octets AMF. Il est une copie de l’objet original et non une référence à l’objet. Toute modification apportée à l’objet dans l’un des programmes de travail n’est pas appliquée à la copie dans l’autre programme de travail.
Outre les mécanismes de transmission de données propres aux programmes de travail, les programmes de travail peuvent également échanger des données à l’aide de l’une des API existantes prenant en charge le partage de données entre deux applications swf :
• écriture de données sur un fichier dans un programme de travail et lecture du fichier dans un autre programme de travail
Lorsque vous partagez une ressource entre deux ou plusieurs programmes de travail, vous devez généralement éviter que divers programmes de travail accèdent en même temps à cette ressource. Par exemple, si plusieurs programmes de travail accèdent à un fichier sur le système de fichiers local, vous risquez de perdre ou d’endommager les données ; en outre, le système d’exploitation risque de ne pas prendre en charge cette opération. Pour éviter les problèmes liés aux accès simultanés, utilisez les classes Mutex et Condition du package flash.concurrent pour contrôler l’accès aux ressources partagées. Contrairement à d’autres mécanismes de partage de données, le moteur de la base de données SQLite est conçu pour un accès simultané et possède un processus transactionnel propre. Plusieurs programmes de travail peuvent accéder à une base de données SQLite sans risquer d’endommager les données. Etant donné que les programmes de travail utilisent différentes occurrences de SQLConnection, chaque programme de travail accède à la base de données dans une transaction distincte. Les opérations de manipulation simultanée de données n’ont aucune incidence sur l’intégrité des données. Voir aussi « Utilisation des bases de données SQL locales dans AIR » à la page 741 Package flash.concurrent
Les présentes sections visent à offrir une présentation générale de la sécurité et non à apporter une explication exhaustive de tous les détails de l’implémentation, des scénarios d’exploitation ou des ramifications de l’utilisation de certaines API. Pour plus d’informations sur les concepts de sécurité de Flash Player, voir la rubrique « Sécurité » du Centre des développeurs de Flash Player à l’adresse www.adobe.com/go/devnet_security_fr.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le modèle de sécurité utilisé par les moteurs d’exécution de Flash Player et d’AIR est en grande partie basé sur le domaine d’origine des fichiers SWF, des contenus HTML, des éléments multimédias et autres actifs chargés. Le code exécutable d’un fichier issu d’un domaine Internet particulier, tel www.exemple.com, peut systématiquement accéder à l’ensemble des données de ce domaine. Ces actifs sont placés dans le même groupe de sécurité, appelé sandbox de sécurité (pour plus d’informations, voir « Sandbox de sécurité » à la page 1087). Par exemple, le code ActionScript d’un fichier SWF peut charger des fichiers SWF, bitmap, audio, texte et tout autre actif appartenant au même domaine. En outre, l’intercodage entre deux fichiers SWF d’un même domaine est systématiquement autorisé, sous réserve qu’ils soient tous deux écrits en ActionScript 3.0. L’intercodage est la capacité du code d’un fichier à accéder aux propriétés, méthodes et objets définis par le code d’un autre fichier. Elle n’est pas prise en charge si les fichiers sont écrits en ActionScript 3.0 pour certains et dans des versions antérieures d’ActionScript pour d’autres. La communication entre ces fichiers sera toutefois possible grâce à la classe LocalConnection. Par ailleurs, un fichier SWF ne peut pas, par défaut, accéder par programmation croisée à des fichiers SWF écrits en ActionScript 3.0 appartenant à d’autres domaines ni charger des données à partir d’autres domaines. Ce type d’accès est néanmoins autorisé par le biais d’un appel à la méthode Security.allowDomain() dans le fichier SWF chargé. Pour plus de détails sur la programmation croisée, voir « Programmation croisée » à la page 1107. Les règles de sécurité élémentaires présentées ci-après s’appliquent toujours par défaut :
• Le code exécutable des fichiers situés dans un sandbox distant ne peut jamais accéder aux données et fichiers locaux. Les moteurs d’exécution de Flash Player et d’AIR considèrent les éléments suivants comme des domaines distincts et configurent un sandbox de sécurité pour chacun d’eux :
Les modèles de sécurité utilisés par les moteurs d’exécution de Flash Player et d’AIR établissent une distinction entre le chargement de contenu et l’accès à des données ou leur extraction. On entend par contenu des fichiers multimédias, notamment les éléments visuels que les moteurs d’exécution peuvent afficher, des fichiers audio et vidéo ou un fichier SWF ou HTML contenant des éléments multimédias affichés. Les données sont des éléments auxquels seul le code peut accéder. Le contenu et les données ne sont pas chargés de la même façon.
NetStream, à l’aide de balises MXML si vous utilisez Flex ou à l’aide de balises HTML dans une application AIR.
Bitmap, des méthodes BitmapData.draw() et BitmapData.drawWithQuality(), de la propriété Sound.id3 ou de la méthode SoundMixer.computeSpectrum() La méthode drawWithQuality est disponible dans Flash Player 11.3 et les versions ultérieures et dans AIR 3.3 et les versions ultérieures.
(un fichier XML, par exemple) par le biais de classes telles que URLStream, URLLoader, FileReference, Socket et XMLSocket. AIR propose d’autres classes de chargement de données, telles que FileStream et XMLHttpRequest. Le modèle de sécurité Flash Player définit différentes règles concernant le chargement de contenu et l’accès aux données. En général, les restrictions sont moindres sur le chargement de contenu que sur l’accès aux données. En règle générale, le contenu (fichiers SWF, bitmap, mp3 et vidéo) peut être chargé de n’importe quelle source, mais s’il provient d’un domaine autre que celui du code ou du contenu à l’origine du chargement, il est placé dans un sandbox de sécurité distinct. Certains obstacles s’appliquent au chargement de contenu :
Si le média chargé est une image, un fichier audio ou une vidéo, ses données (par exemple données de pixels ou sons) sont accessibles pour un fichier SWF situé en dehors de son sandbox de sécurité, à condition que le domaine de ce fichier SWF ait été inclus dans un fichier de régulation d’URL dans le domaine d’origine du média. Pour plus d’informations, voir « Accès aux médias chargés comme s’il s’agissait de données » à la page 1111. Les données chargées peuvent également provenir de fichiers texte ou XML chargés avec l’objet URLLoader. Là encore, l’accès à des données situées dans un autre sandbox de sécurité nécessite l’attribution des autorisations suffisantes par le biais d’un fichier de régulation d’URL placé dans le domaine d’origine. Pour plus d’informations, voir « Utilisation de URLLoader et URLStream » à la page 1113.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les ordinateurs clients peuvent obtenir des fichiers individuels contenant du code, un contenu et des données à partir de sources diverses, telles que des sites Web externes, un système de fichiers local ou une application AIR installée. Les moteurs d’exécution de Flash Player et d’AIR associent chaque fichier de code et autres ressources (objets partagés, fichiers bitmap, son, vidéo et données) à des sandbox de sécurité en fonction de leur origine au moment du chargement. Les sections suivantes passent en revue les règles mises en place par les moteurs d’exécution pour contrôler ce à quoi un code ou un contenu peut accéder au sein d’un sandbox donné. Pour plus de détails sur la sécurité de Flash Player, voir la rubrique « Sécurité » du Centre des développeurs Flash Player à l’adresse www.adobe.com/go/devnet_security_fr.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les moteurs d’exécution de Flash Player et d’AIR classent les actifs (notamment les fichiers SWF) issus d’Internet dans des sandbox distincts correspondant à leur domaine d’origine. Les actifs chargés d’example.com ne partagent par exemple pas le même sandbox de sécurité que les actifs issus de foo.org. Par défaut, ces fichiers sont autorisés à accéder à toutes les ressources issues de leur propre serveur. Il est possible d’autoriser les fichiers SWF distants à accéder à des données d’autres domaines à l’aide d’autorisations explicites portant sur les sites Web et les auteurs, par exemple des fichiers de régulation d’URL et la méthode Security.allowDomain(). Pour plus d’informations, voir « Contrôles de site Web (fichiers de régulation) » à la page 1095 et « Contrôles de création (développeur) » à la page 1099. Les fichiers SWF distants ne peuvent pas charger de fichiers ou de ressources locales. Pour plus de détails sur la sécurité de Flash Player, voir la rubrique « Sécurité » du Centre des développeurs Flash Player à l’adresse www.adobe.com/go/devnet_security_fr.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Un fichier est dit local s’il est référencé par le biais du protocole file: ou d’un chemin UNC (Universal Naming Convention). Les fichiers SWF locaux sont placés dans l’un de quatre sandbox locaux :
La communication entre le sandbox local avec réseau et le sandbox local avec système de fichiers est strictement interdite, tout comme la communication entre le sandbox local avec système de fichiers et le sandbox distant. Elles ne peuvent pas être autorisées par une application Flash Player ni par un utilisateur ou un administrateur. La programmation croisée entre les fichiers HTML et SWF locaux (par exemple à l’aide de la classe ExternalInterface) exige que les deux fichiers impliqués se trouvent dans le sandbox local approuvé. Cette contrainte vient du fait que les modèles de sécurité locaux des navigateurs diffèrent de celui de Flash Player. Les fichiers SWF du sandbox local avec réseau ne peuvent pas charger des fichiers SWF du sandbox local avec système de fichiers. Les fichiers SWF du sandbox local avec système de fichier ne peuvent pas charger des fichiers SWF du sandbox local avec réseau.
Le moteur d’exécution d’Adobe AIR ajoute un autre sandbox, dit sandbox de l’application, au modèle de sandbox de sécurité de Flash Player. Les fichiers installés dans le cadre d’une application AIR sont chargés dans le sandbox de l’application. A tout autre fichier chargé par l’application s’appliquent des restrictions de sécurité correspondant aux limites stipulées par le modèle de sécurité de Flash Player standard. Lors de l’installation d’une application, tous les fichiers intégrés à un package AIR sont installés sur l’ordinateur de l’utilisateur dans le répertoire de l’application. Les développeurs peuvent référencer ce répertoire dans le code via le modèle d'URL app:/ (voir « Modèles d’URI » à la page 845). Tous les fichiers qui se trouvent dans l’arborescence du répertoire de l’application sont affectés au sandbox de l’application lorsque celle-ci est exécutée. Le contenu du sandbox de l’application est doté de tous les privilèges disponibles pour une application AIR, y compris l’interaction avec le système des fichiers locaux.
Les interfaces de programmation ActionScript réservées au contenu du sandbox de sécurité de l’application sont dotées du logo AIR dans le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash. L’utilisation de ces interfaces de programmation dans d’autres sandbox provoque le renvoi d’une exception SecurityError. Pour un contenu HTML, dans un objet HTMLLoader, toutes les interfaces de programmation JavaScript d’AIR (celles qui sont disponibles via la propriété window.runtime ou l’objet air lors de l’utilisation du fichier AIRAliases.js), sont mises à la disposition du contenu dans le sandbox de sécurité de l’application. Le contenu HTML d’un autre sandbox n’ayant pas accès à la propriété window.runtime, il lui est impossible d’accéder aux interfaces de programmation AIR ou Flash Player. Les restrictions complémentaires suivantes s’appliquent au content exécuté au sein du sandbox de l’application AIR :
SWF chargé. Cela lui évite de recharger le contenu plusieurs fois.
Contrairement au contenu du sandbox de sécurité de l’application, celui de JavaScript dans un sandbox de sécurité hors application peut à tout moment appeler la fonction eval() pour exécuter dynamiquement le code généré. Des restrictions s’appliquent néanmoins dans AIR au contenu JavaScript exécuté dans un sandbox de sécurité hors application, Parmi ces API figurent :
• Un contenu HTML dans un sandbox de sécurité distant (réseau) ne peut charger que du contenu CSS, image, iframe et img à partir d’un domaine distant (à partir d’URL du réseau).
Pour plus d’informations, voir « Restrictions relatives au code pour un contenu dans des sandbox différents » à la page 1130.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Un utilisateur ou l’administrateur d’un ordinateur peut spécifier si un fichier SWF local est approuvé, lui permettant ainsi de charger des données de tous les domaines, locaux ou réseau. Cette caractéristique est définie dans les répertoires Flash Player Trust global et utilisateur. Pour plus d’informations, voir « Contrôles administrateur » à la page 1092 et « Contrôles utilisateur » à la page 1093. Pour plus d’informations sur les sandbox locaux, voir « Sandbox locaux » à la page 1087. Adobe Flash Professional Vous pouvez configurer un fichier SWF pour le sandbox local avec système de fichiers ou le sandbox local avec réseau en définissant les paramètres de publication du document dans l’outil de création.
Vous pouvez configurer un fichier SWF pour le sandbox local avec système de fichiers ou le sandbox local avec réseau en définissant l’indicateur use-network dans le compilateur Adobe Flex. Pour plus d’informations, voir « A propos des options du compilateur d’applications » dans Développement et déploiement d’applications Adobe Flex 3.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le modèle de sécurité d’exécution du client Flash Player repose sur les ressources, c’est-à-dire des objets tels que des fichiers SWF, des données locales et des URL Internet. Les parties prenantes détiennent ou utilisent ces ressources. Elles peuvent exercer un contrôle (via des paramètres de sécurité) sur leurs propres ressources, chaque ressource ayant quatre parties prenantes. Flash Player applique une stricte hiérarchie d’autorité sur ces contrôles, comme le montre l’illustration suivante :
Pour une application AIR, ces contrôles d’autorisations ne s’appliquent qu’au contenu exécuté en dehors de son sandbox.
Un fichier SWF peut obtenir des informations sur les fonctions désactivées en appelant les propriétés Capabilities.avHardwareDisable et Capabilities.localFileReadDisable. Toutefois, la plupart des paramètres du fichier mms.cfg ne peuvent être interrogés à partir d’ActionScript. Pour mettre en place sur un ordinateur des stratégies de confidentialité et de sécurité indépendantes des applications, le fichier mms.cfg doit être uniquement modifié par un administrateur système. Le fichier mms.cfg n’est pas destiné aux programmes d’installation des applications. Bien qu’un programme d’installation exécuté avec des privilèges administrateur puisse modifier le contenu du fichier mms.cfg, Adobe considère cette pratique comme une violation de la confiance de l’utilisateur et presse les créateurs de programmes d’installation de ne jamais modifier le fichier mms.cfg. Le fichier mms.cfg est enregistré dans le chemin suivant :
(par exemple, C:\windows\system32\Macromed\Flash\mms.cfg) Flash Player Trust contenant le texte suivant approuve tous les fichiers placés dans le répertoire spécifié et ses sousrépertoires : # Trust files in the following directories: C:\Documents and Settings\All Users\Documents\SampleApp
Pour éviter les conflits, attribuez au fichier de configuration Trust un nom correspondant à l’application installée, suivi de l’extension de fichier .cfg. En tant que développeur diffusant un fichier SWF à exécuter localement par le biais d’un programme d’installation, vous pouvez faire en sorte que ce programme d’installation ajoute un fichier de configuration au répertoire Flash Player Trust global afin d’accorder des privilèges complets au fichier que vous diffusez. Le programme d’installation doit être exécuté par un utilisateur doté de droits d’administration. Contrairement au fichier mms.cfg, le répertoire Flash Player Trust global est prévu pour les programmes d’installation devant accorder des autorisations. Il permet aux administrateurs et aux programmes d’installation de désigner des applications locales approuvées. Il existe également des répertoires Flash Player Trust destinés aux utilisateurs individuels (voir « Contrôles utilisateur » à la page 1093).
Flash Player 9 et les versions ultérieures Flash Player propose trois mécanismes de définition des autorisations au niveau utilisateur : l’interface de paramétrage, le Gestionnaire des paramètres et le répertoire Flash Player Trust utilisateur.
L’interface de paramétrage est un mécanisme interactif qui permet de configurer rapidement les paramètres d’un domaine donné. Le Gestionnaire des paramètres, avec son interface plus détaillée, permet d’effectuer des modifications globales sur les autorisations de plusieurs domaines ou de tous. En outre, si un fichier SWF nécessite une nouvelle autorisation qui oblige à prendre des décisions en cours d’exécution concernant la sécurité ou la confidentialité, des boîtes de dialogue s’affichent dans lesquelles les utilisateurs peuvent régler certains paramètres de Flash Player. Le Gestionnaire des paramètres et l’interface de paramétrage proposent des options associées à la sécurité telles que les paramètres de la caméra et du microphone, les paramètres de stockage d’objets partagés, les paramètres relatifs au contenu hérité, etc. Les applications AIR ne disposent ni du Gestionnaire des paramètres, ni de l’interface de paramétrage. Remarque : les réglages effectués dans le fichier mms.cfg (voir « Contrôles administrateur » à la page 1092) n'apparaissent pas dans le Gestionnaire des paramètres. Pour plus d’informations sur le Gestionnaire des paramètres, voir www.adobe.com/go/settingsmanager_fr.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les utilisateurs et programmes d’installation peuvent approuver des fichiers SWF locaux spécifiques. Ces fichiers SWF sont associés au sandbox local approuvé. Ils peuvent interagir avec tout autre fichier SWF puisqu’ils peuvent charger des données stockées localement ou à distance. Pour approuver un fichier, l’utilisateur le désigne dans le répertoire Player Trust utilisateur, qui se trouve dans le même répertoire que la zone de stockage des objets partagés Flash, aux emplacements suivants (ces emplacements sont spécifiques à l’utilisateur actif) :
(par exemple, C:\Documents and Settings\JohnD\Application Data\Macromedia\Flash « Contrôles administrateur » à la page 1092).
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Si vous souhaitez rendre les données d’un serveur Web accessibles aux fichiers SWF issus de domaines différents, vous pouvez créer un fichier de régulation sur votre serveur. Un fichier de régulation est un fichier XML résidant à un emplacement spécifique sur votre serveur. Les fichiers de régulation ont une incidence sur l’accès à certains actifs, notamment les suivants :
• Le chargement des fichiers XML et texte • L’importation de fichiers SWF à partir d’autres domaines de sécurité dans le domaine du fichier SWF à l’origine du chargement
XMLSocket établissent des connexions socket, qui fonctionnent avec des flux de données et non des documents chargés. Flash Player prenant en charge deux types de connexions serveur, il existe deux types de fichiers de régulation : les fichiers de régulation d’URL et les fichiers de régulation socket.
Flash Player exige que les fichiers de régulation soient transmis par le biais du protocole utilisé par la tentative de connexion. Par exemple, si vous placez un fichier de régulation sur un serveur HTTP, les fichiers SWF issus d’autres domaines sont autorisés à charger les données qu’il contient en tant que serveur HTTP. Cependant, si vous ne fournissez aucun fichier de régulation socket sur ce même serveur, vous empêchez les fichiers SWF issus d’autres domaines d’accéder au serveur au niveau socket. La méthode de récupération du fichier de régulation doit donc correspondre à la méthode de connexion. L’utilisation et la syntaxe des fichiers de régulation, tels qu’ils s’appliquent aux fichiers SWF publiés pour Flash Player 10, sont décrites dans les paragraphes suivants (l’implémentation des fichiers de régulation est légèrement différente dans les versions antérieures de Flash Player, dont la sécurité a été renforcée ultérieurement). Pour plus d’informations sur les fichiers de régulation, voir le chapitre « Modifications du fichier de régulation dans Flash Player 9 » dans le Centre des développeurs Flash Player à l’adresse www.adobe.com/go/devnet_security_fr.
Par défaut, Flash Player (et le contenu AIR qui ne figure pas dans le sandbox d’application AIR) commence par rechercher le fichier de régulation d’URL crossdomain.xml dans le répertoire racine du serveur, puis recherche un fichier de régulation socket sur le port 843. Tout fichier résidant à l’un de ces emplacements constitue le fichier de régulation maître (dans le cas des connexions socket, Flash Player recherche également un fichier de régulation socket sur le port utilisé par la connexion principale. Un fichier de régulation se trouvant sur ce port ne constitue cependant pas un fichier de régulation maître). Outre la définition des autorisations d’accès, le fichier de régulation maître peut également contenir une instruction meta-policy. Une méta-régulation détermine les emplacements auxquels peuvent résider les fichiers de régulation. La méta-régulation par défaut des fichiers de régulation d’URL correspond à « master-only » ; autrement dit, /crossdomain.xml est le seul fichier de régulation autorisé sur le serveur. La méta-régulation par défaut des fichiers de régulation socket correspond à « all » ; autrement dit, tout socket figurant sur l’hôte peut servir un fichier de régulation de socket. Remarque : dans Flash Player 9 et les versions antérieures, la méta-régulation par défaut des fichiers de régulation d’URL correspondait à « all ». Tout répertoire peut donc contenir un fichier de régulation. Si vous avez déployé des applications qui chargent d’autres fichiers de régulation que le fichier /crossdomain.xml par défaut, et que ces applications sont maintenant susceptibles de s’exécuter dans Flash Player 10, vous (ou l’administrateur du serveur) devez modifier le fichier de régulation maître pour autoriser l’utilisation d’autres fichiers de régulation. Pour plus d’informations sur la définition d’une méta-régulation différente, voir le chapitre « Modifications du fichier de régulation dans Flash Player 9 » dans le Centre des développeurs Flash Player à l’adresse www.adobe.com/go/devnet_security_fr. Un fichier SWF peut effectuer une recherche sur un nom de fichier de régulation ou un emplacement différent en appelant la méthode Security.loadPolicyFile(). Cependant, si le fichier de régulation maître ne spécifie pas que l’emplacement cible peut servir des fichiers de régulation, l’appel à loadPolicyFile() est sans effet, même si un fichier de régulation se trouve à l’emplacement en question. Appelez loadPolicyFile() avant d’exécuter toute opération réseau requérant le fichier de régulation. Flash Player place automatiquement les requêtes réseau derrière les tentatives de requête de fichier de régulation correspondantes. Il est donc acceptable, par exemple, d’appeler Security.loadPolicyFile() immédiatement avant de lancer une opération réseau. Lorsqu’il recherche un fichier de régulation maître,. Flash Player attend une réponse du serveur pendant trois secondes. En l’absence d’une réponse, l’application considère comme acquis qu’il n’existe pas de fichier de régulation maître. Toutefois, si aucune valeur de dépassement de délai par défaut est définie pour les appels à loadPolicyFile(), Flash Player suppose que le fichier appelé existe et attend aussi longtemps que nécessaire pour le charger. Pour avoir la certitude qu’un fichier de régulation maître est chargé, appelez-le donc explicitement par le biais de loadPolicyFile(). Bien que la méthode s’appelle Security.loadPolicyFile(), aucun fichier de régulation n’est chargé tant qu’un appel réseau requérant un tel fichier n’a pas été émis. Les appels à loadPolicyFile() indiquent simplement à Flash Player où rechercher les fichiers de régulation, le cas échéant. Aucune notification indiquant l’initiation ou la fin d’une requête de fichier de régulation n’est envoyée, car cela n’est pas nécessaire. Flash Player recherche les fichiers de régulation de manière asynchrone et attend automatiquement que ces recherches aient abouti pour établir des connexions.
Un fichier de régulation d’URL s’applique uniquement au répertoire dans lequel il est chargé et à ses sous-répertoires. Un fichier de régulation placé dans le répertoire racine s’applique à l’ensemble du serveur. En revanche, un fichier de régulation chargé d’un sous-répertoire quelconque s’applique uniquement à celui-ci et à ses sous-répertoires. Un fichier de régulation contrôle uniquement l’accès au serveur sur lequel il réside. Par exemple, un fichier de régulation situé dans https://www.adobe.com:8080/crossdomain.xml ne s’applique qu’aux appels de chargement de données passés vers www.adobe.com sur HTTPS au port 8080.
Un fichier de régulation contient une seule balise cross-domain-policy, qui contient elle-même aucune ou plusieurs balises allow-access-from. Chaque balise allow-access-from contient un attribut domain qui spécifie une adresse IP exacte, un domaine exact ou un domaine générique (tout domaine). Les domaines génériques sont indiqués de deux façons :
• Par un astérisque suivi d’un suffixe, qui représente uniquement les domaines se terminant par ce suffixe Les suffixes doivent commencer par un point. Cependant, les domaines génériques suivis de suffixes peuvent correspondre à des domaines qui sont composés uniquement du suffixe sans le point de séparation. xyz.com, par exemple, fait partie de *.xyz.com. L’utilisation de caractères génériques est interdite dans les spécifications de domaine IP. L’exemple suivant présente un fichier de régulation d’URL qui autorise l’accès à des fichiers SWF issus des domaines *.example.com, www.friendOfExample.com et 192.0.34.166 : <?xml version="1.0"?> <cross-domain-policy> <allow-access-from domain="*.example.com" /> Si les données à charger se trouvent sur un serveur HTTPS, alors que le fichier SWF à l’origine du chargement réside sur un serveur HTTP, Adobe recommande le transfert du fichier SWF sur un serveur HTTPS. Ce faisant, toutes les copies de vos données sécurisées sont protégées par HTTPS. Cependant si vous décidez que vous devez conserver le fichier SWF à l’origine du chargement sur un serveur HTTP, ajoutez l’attribut secure="false" à la balise allowaccess-from, comme le montre le code suivant : <allow-access-from domain="www.example.com" secure="false" />
<cross-domain-policy> Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le chargement des données à partir d’un serveur ou la connexion à un socket sont des opérations asynchrones. Flash Player attend simplement la fin du téléchargement du fichier de régulation avant de lancer l’opération principale. En revanche, l’extraction de données de pixel d’images ou de données d’échantillonnage de sons est une opération synchrone. Le fichier de régulation doit donc être chargé pour que vous puissiez extraire les données. Lors du chargement du média, spécifiez que le fichier de régulation doit être recherché :
<img checkPolicyFile = "true" src = "example.jpg">
Lorsque vous définissez l’un de ces paramètres, Flash Player commence par vérifier si des fichiers de régulation ont déjà été téléchargés pour ce domaine. Il recherche ensuite le fichier de régulation à l’emplacement par défaut sur le serveur, puis les instructions <allow-access-from> et une méta-régulation. En dernier lieu, il contrôle tout appel en attente à la méthode Security.loadPolicyFile() pour vérifier s’il s’applique.
Security.allowDomain(), qui accorde des droits aux fichiers SWF du domaine que vous spécifiez. Dans l’exemple suivant, un fichier SWF autorise l’accès des fichiers SWF servis à partir du domaine www.example.com : Security.allowDomain("www.example.com")
La méthode Security.allowDomain() sert avant tout à permettre aux fichiers SWF situés dans un domaine externe d’effectuer une programmation croisée avec le fichier SWF qui appelle la méthode Security.allowDomain(). Pour plus de détails sur la programmation croisée, voir « Programmation croisée » à la page 1107. La spécification de l’adresse IP en tant que paramètre de Security.allowDomain() n’autorise pas l’accès de toutes les parties provenant de l’adresse IP spécifiée. Au contraire, elle autorise l’accès d’une partie présentant une URL identique à l’adresse IP spécifiée, plutôt qu’un nom de domaine renvoyant à l’adresse IP. Par exemple, si le nom de domaine www.example.com renvoie à l’adresse IP 192.0.34.166, un appel à Security.allowDomain("192.0.34.166") ne donne pas accès à www.example.com. Vous pouvez transmettre le caractère générique "*" à la méthode Security.allowDomain() pour permettre l’accès à partir de tous les domaines. Soyez prudent lorsque vous utilisez le caractère générique "*" car celui-ci autorise les fichiers SWF issus de tous les domaines à effectuer une programmation dans le fichier SWF appelant. ActionScript inclut une seconde API d’autorisation appelée Security.allowInsecureDomain(). Cette méthode joue le même rôle que la méthode Security.allowDomain() à la différence suivante : lorsqu’elle est appelée à partir d’un fichier SWF servi par une connexion HTTPS, elle autorise l’accès à ce fichier appelant pour d’autres fichiers SWF servis à partir d’un protocole non sécurisé, tel HTTP. Cependant, il est déconseillé de permettre la programmation croisée entre des fichiers issus d’un protocole sécurisé et ceux provenant d’un protocole qui ne l’est pas. Cette pratique est susceptible de rendre le contenu vulnérable aux attaques d’espionnage. Ces attaques se déroulent comme suit, par exemple : puisque la méthode Security.allowInsecureDomain() permet aux fichiers SWF servis sur des connexions HTTP d’accéder aux données HTTPS sécurisées, un attaquant qui s’interposerait entre le serveur HTTP et les utilisateurs pourraient remplacer votre fichier SWF HTTP par un fichier de son cru afin d’accéder à vos données HTTPS. Important : le code exécuté dans le sandbox de l’application AIR n’est pas autorisé à appeler la méthode allowDomain() ou allowInsecureDomain() de la classe Security. Autre méthode importante liée à la sécurité, Security.loadPolicyFile() permet à Flash Player de rechercher le fichier de régulation à un autre emplacement. Pour plus d’informations, voir « Contrôles de site Web (fichiers de régulation) » à la page 1095.
Les API de réseau peuvent faire l’objet de deux types de restriction : Pour empêcher les activités nuisibles, l’accès aux ports généralement réservés est bloqué. Vous ne pouvez pas passer outre ces blocages dans votre code. Pour contrôler l’accès au réseau par le biais d’autres ports d’un fichier SWF, vous pouvez utiliser le paramètre allowNetworking.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures A l’instar des navigateurs, Flash Player et Adobe AIR imposent des restrictions sur l’accès HTTP à certains ports. Les requêtes HTTP sont interdites sur certains ports standard traditionnellement réservés aux types de serveurs autres que HTTP. Toute API accédant à une URL réseau est soumise aux restrictions affectant ces ports. Les API qui appellent directement des sockets, telles que Socket.connect() et XMLSocket.connect(), ou les appels à Security.loadPolicyFile() dans lesquels un fichier de régulation socket est en cours de chargement font exception à cette règle. Les connexions socket sont autorisées ou refusées par le biais de fichiers de régulation socket sur le serveur cible. Les API ActionScript 3.0 concernées par le blocage des ports sont les suivantes : FileReference.download(),FileReference.upload(), Loader.load(), Loader.loadBytes(), navigateToURL(), NetConnection.call(), NetConnection.connect(), NetStream.play(), Security.loadPolicyFile(), sendToURL(), Sound.load(), URLLoader.load(), URLStream.load()
<img> dans les champs de texte et au chargement de fichiers SWF sur une page HTML à l’aide des balises <object> et <embed>. Le blocage des ports s’applique également à l’utilisation de la balise <img> dans les champs de texte et au chargement de fichiers SWF sur une page HTML à l’aide des balises <object> et <embed>. Les ports bloqués sont les suivants : HTTP: 20 (ftp data), 21 (ftp control) HTTP et FTP : 1 (tcpmux), 7 (echo), 9 (discard), 11 (systat), 13 (daytime), 15 (netstat), 17 (qotd), 19 (chargen), 22 (ssh), 23 (telnet), 25 (smtp), 37 (time), 42 (name), 43 (nicname), 53 (domain), 77 (priv-rjs), 79 (finger), Dernière mise à jour le 27/4/2013
Le paramètre allowNetworking s’utilise surtout lorsque le fichier SWF et la page HTML qui l’accueille appartiennent à des domaines différents. Il est déconseillé d’utiliser la valeur "internal" ou "none" si le fichier SWF en cours de chargement appartient au même domaine que les pages HTML qui l’accueillent, car vous ne pouvez pas garantir qu’un fichier SWF est toujours chargé avec la page HTML prévue. Des personnes mal intentionnées pourraient charger un fichier SWF à partir de votre domaine sans les pages HTML correspondantes, auquel cas la restriction allowNetworking n’aurait pas l’effet escompté. L’appel d’une API interdite renvoie une exception SecurityError. Ajoutez le paramètre allowNetworking et définissez sa valeur dans les balises <object> et <embed> de la page HTML contenant une référence au fichier SWF, comme indiqué dans l’exemple suivant : <object classic="clsid:d27cdb6e-ae6d-11cf-96b8-444553540000" Code base="http://fpdownload.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,124, Professional (pas ActionScript) est bloqué lors de l’exécution.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Player version 9.0.27.0 et les versions ultérieures prennent en charge le mode plein écran, dans lequel le contenu Flash Player peut remplir tout l’écran. Pour passer en mode plein écran, la propriété displayState de la scène est définie avec la constante StageDisplayState.FULL_SCREEN. Pour plus d’informations, voir « Utilisation du mode Plein écran » à la page 173. L’exécution de fichiers SWF dans un sandbox distant impose la prise en considération de certains points de sécurité. L’activation du mode plein écran s’effectue dans les balises <object> et <embed> de la page HTML qui contient la référence au fichier SWF. Pour ce faire, ajoutez le paramètre allowFullScreen et attribuez-lui la valeur "true" (la valeur par défaut est "false"), comme le montre l’exemple suivant : <object classid="clsid:d27cdb6e-ae6d-11cf-96b8-444553540000" codebase="http://fpdownload.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0, 18,0" width="600" height="400" id="test" align="middle"> <param name="allowFullScreen" value="true" /> Pour le contenu qui s’exécute dans un navigateur, l’utilisation du clavier est restreinte en mode plein écran. Dans Flash Player 9, seuls les raccourcis clavier qui réinitialisent le mode normal de l’application (tel appuyer sur la touche Echap) sont pris en charge. Les utilisateurs ne sont pas autorisés à entrer du texte dans un champ de texte ou à naviguer à l’écran. Flash Player 10 (et versions ultérieures) prend en charge certaines touches hors impression, notamment les touches fléchées, la barre d’espacement et la touche de tabulation. La saisie de texte est néanmoins toujours interdite.
Pour désactiver le mode plein écran pour les fichiers exécutés dans des navigateurs, les administrateurs peuvent définir FullScreenDisable = 1 dans le fichier mms.cfg. Pour plus d'informations, voir « Contrôles administrateur » à la page 1092. Pour accéder au mode plein écran dans un navigateur, un fichier SWF doit se trouver au sein d’une page HTML.
Flash Player 11.3 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Flash Player 11.3 et les versions ultérieures prennent en charge le mode interactif plein écran, dans lequel le contenu s’exécutant dans Flash Player peut remplir la totalité de l’écran et prendre en charge la saisie de texte. Pour accéder au mode interactif plein écran, la propriété displayState de la scène est définie sur la constante StageDisplayState.FULL_SCREEN_INTERACTIVE. Pour plus d’informations, voir « Utilisation du mode Plein écran » à la page 173. L’exécution de fichiers SWF dans un sandbox distant impose la prise en considération de certains points de sécurité. L’activation du mode plein écran s’effectue dans les balises <object> et <embed> de la page HTML qui contient la référence au fichier SWF. Pour ce faire, ajoutez le paramètre allowFullScreenInteractive et attribuez-lui la valeur "true" (la valeur par défaut est "false"), comme le montre l’exemple suivant : <object classid="clsid:d27cdb6e-ae6d-11cf-96b8-444553540000" codebase="http://fpdownload.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0, 18,0" width="600" height="400" id="test" align="middle"> <param name="allowFullScreenInteractive" value="true" /> Pour désactiver le mode interactif plein écran pour les fichiers exécutés dans des navigateurs, les administrateurs peuvent définir FullScreenInteractiveDisable = 1 dans le fichier mms.cfg. Pour plus d'informations, voir « Contrôles administrateur » à la page 1092. Pour accéder au mode interactif plein écran dans un navigateur, un fichier SWF doit se trouver au sein d’une page HTML.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Le contenu Flash Player et AIR peut charger un grand nombre de types de contenus, notamment :
• Images • Son • Vidéo • Fichiers HTML (AIR uniquement) • JavaScript (AIR uniquement)
Lorsque vous chargez un fichier SWF d’une source non approuvée (telle qu’un domaine autre que celui du fichier SWF racine de l’objet Loader), il peut s’avérer utile de définir un masque pour ce dernier, afin d’empêcher le contenu chargé, qui est un enfant de l’objet Loader, d’apparaître dans des parties de la scène qui ne relèvent pas de ce masque, comme illustré par le code suivant :
Loader, le code ActionScript des fichiers SWF du domaine Loader peut accéder à l’image chargée. En d’autres termes, vous pouvez utiliser soit la propriété Loader.content pour obtenir une référence à un objet Bitmap qui représente l’image chargée, soit la méthode BitmapData.draw() ou la méthode BitmapData.drawWithQuality() pour accéder aux pixels de l’image chargée. La méthode drawWithQuality est disponible dans Flash Player 11.3 et les versions ultérieures et dans AIR 3.3 et les versions ultérieures.
Cette propriété peut être appelée pour un fichier SWF provenant d’un autre domaine que celui du fichier qui contient l’objet Loader. Seules les deux valeurs suivantes sont actuellement prises en charge par la propriété securityDomain : null (par défaut) et SecurityDomain.currentDomain. Si vous spécifiez SecurityDomain.currentDomain, le fichier SWF chargé est importé sur demande dans le sandbox du fichier SWF à l’origine du chargement. Par conséquent le fichier fonctionne comme s’il avait été chargé à partir du serveur du fichier appelant. Cette opération n’est permise que si le fichier de régulation d’URL se trouve sur le serveur du fichier SWF chargé, pour qu’il soit accessible au domaine du fichier SWF à l’origine du chargement. Si le fichier nécessaire est détecté, les deux fichiers peuvent librement effectuer une programmation croisée dès le début du chargement, puisqu’ils se trouvent dans le même sandbox. Notez que l’importation dans le sandbox peut presque être remplacée par un chargement ordinaire suivi d’un appel du fichier SWF chargé à la méthode Security.allowDomain(). Cette dernière peut s’avérer plus simple à utiliser puisque le fichier SWF chargé se trouve alors dans son sandbox naturel, pouvant ainsi accéder aux ressources de son propre serveur.
Ainsi, vous pouvez uniquement spécifier un domaine d’application cible si le fichier SWF chargé provient de votre propre de domaine de sécurité, soit parce qu’il appartient à votre propre serveur, soit parce que vous l’avez importé dans votre domaine de sécurité à l’aide de la propriété securityDomain. Si vous spécifiez un domaine d’application mais que le fichier SWF chargé fait partie d’un domaine de sécurité différent, le domaine que vous spécifiez dans applicationDomain est ignoré. Pour plus d’informations, voir « Utilisation de domaines d’application » à la page 152.
Chargement de sons et vidéos Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures En dehors du contenu du sandbox local avec système de fichiers, tout contenu est autorisé à charger des éléments audio et vidéo en provenance d’un réseau grâce aux méthodes Sound.load(), NetConnection.connect() et NetStream.play(). Seul le contenu du sandbox local avec système de fichiers et du sandbox d’application AIR peut charger des fichiers multimédias issus du système de fichiers local. Seul le contenu du sandbox local avec système de fichiers, du sandbox d’application AIR ou du sandbox approuvé localement peut accéder aux données de ces fichiers chargés. D’autres restrictions s’appliquent à l’accès aux données à partir d’un média chargé. Pour plus d’informations, voir « Accès aux médias chargés comme s’il s’agissait de données » à la page 1111.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La balise <img> permet de charger des fichiers SWF et bitmap dans un champ de texte, comme le montre le code suivant : <img src = 'filename.jpg' id = 'instanceName' >
TextField, comme dans le code suivant : var loadedObject:DisplayObject = myTextField.getImageReference('instanceName');
à leur origine. Lorsque vous chargez un fichier image à l’aide de la balise <img> d’un champ de texte, l’accès aux données de l’image peut être autorisé par le biais d’un fichier de régulation d’URL. Vous pouvez vérifier l’existence d’un tel fichier en ajoutant l’attribut checkPolicyFile à la balise <img>, comme le montre le code suivant : <img src = 'filename.jpg' checkPolicyFile = 'true' id = 'instanceName' >
Toutefois, si vous faites référence à la propriété content de l’objet Loader pour accéder au média chargé, des règles de sécurité s’appliquent. Si le contenu est une image, vous devez implémenter un fichier de régulation d’URL ; s’il s’agit d’un fichier SWF, vous devez modifier le code de ce fichier de manière qu’il appelle la méthode allowDomain(). Adobe AIR Dans le sandbox de l’application, les balises <img> d’un champ de texte sont ignorées pour empêcher les attaques d’hameçonnage. Par ailleurs, le code exécuté dans le sandbox de l’application n’est pas autorisé à appeler la méthode de sécurité allowDomain().
Flash Media Server utilise le protocole RTMP (Real-Time Media Protocol) pour servir des données, des sons et des vidéos. Vous pouvez charger ces données multimédias par le biais de la méthode connect() de la classe NetConnection, en transmettant une URL RTMP en tant que paramètre. Flash Media Server peut restreindre les connexions et empêcher le téléchargement du contenu, selon le domaine du fichier requis. Pour plus d’informations, voir la documentation de Flash Media Server disponible en ligne à l’adresse suivante : www.adobe.com/go/learn_fms_docs_fr. Pour extraire des graphiques d’exécution et des données audio de flux RTMP par le biais des méthodes BitmapData.draw(), BitmapData.drawWithQuality() et SoundMixer.computeSpectrum() , vous devez autoriser l’accès au serveur. Les propriétés ActionScript côté serveur Client.videoSampleAccess et Client.audioSampleAccess permettent d’accéder à des répertoires spécifiques de Flash Media Server. Pour plus d’informations, voir le Guide de référence ActionScript de Flash Media Server côté serveur. (La méthode drawWithQuality est disponible dans Flash Player 11.3 et les versions ultérieures et dans AIR 3.3 et les versions ultérieures.)
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Si deux fichiers SWF écrits en ActionScript 3.0 ou deux fichiers HTML exécutés dans AIR sont transmis à partir d’un même domaine (supposons que l’URL du premier fichier SWF est http://www.example.com/swfA.swf et celle du second est http://www.example.com/swfB.swf), le code défini dans l’un des fichiers peut examiner et modifier les variables, objets, propriétés, méthodes, etc. de l’autre fichier, et inversement. On parle d’intercodage.
Dans tout contexte inter-domaines, il est important d’identifier clairement les parties impliquées. Dans le cadre de cette étude, le fichier effectuant la programmation croisée sera appelé partie procédant à l’accès (habituellement le fichier SWF procédant à l’accès), et l’autre côté sera appelé partie cible (généralement le fichier SWF cible). Lorsque siteA.swf programme siteB.swf, siteA.swf est la partie procédant à l’accès et site.B.swf la partie cible, comme le montre l’illustration suivante :
En dehors de la protection des fichiers SWF contre les scripts inter-domaines provenant d’autres fichiers SWF, Flash Player protège également les fichiers SWF contre ce type de script provenant des fichiers HTML. La programmation HTML vers SWF est possible au moyen de rappels effectués avec la méthode ExternalInterface.addCallback(). Lorsque la programmation HTML vers SWF franchit les limites du domaine, le SWF cible doit également appeler Security.allowDomain(), comme s’il avait été appelé par un fichier SWF, faute de quoi l’opération échoue. Pour plus d’informations, voir « Contrôles de création (développeur) » à la page 1099. Flash Player fournit en outre des contrôles de sécurité spécifiques à la programmation SWF vers HTML. Pour plus d’informations, voir « Contrôle de l’accès URL externe » à la page 1118.
Certaines propriétés et méthodes de l’objet Stage sont disponibles pour tout sprite ou clip de la liste d’affichage. Le premier fichier SWF chargé est cependant considéré comme le propriétaire de l’objet Stage. Par défaut, les propriétés et méthodes suivantes de l’objet Stage sont uniquement disponibles pour les fichiers SWF du même sandbox de sécurité que le propriétaire de l’objet Stage : Propriétés
Il existe également des restrictions sur les méthodes removeChildAt() et swapChildrenAt(), mais ce sont des restrictions différentes des autres. Pour appeler ces méthodes, le code ne doit pas se trouver dans le même domaine que le propriétaire de l’objet Stage mais dans le même domaine que le propriétaire du ou des objets enfant concernés ; en outre, les objets enfant peuvent appeler la méthode Security.allowDomain().
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La capacité d’un fichier SWF d’accéder aux objets d’affichage chargés à partir d’autres sandbox fait l’objet de restrictions. Pour qu’un fichier SWF puisse accéder à un objet d’affichage créé par un autre fichier SWF dans un sandbox différent, le fichier SWF cible doit appeler la méthode Security.allowDomain() pour autoriser l’accès du domaine du fichier SWF procédant à l’appel. Pour plus d’informations, voir « Contrôles de création (développeur) » à la page 1099. Pour accéder à un objet Bitmap chargé par un objet Loader, il faut qu’un fichier de régulation d’URL existe sur le serveur d’origine du fichier image et que ce fichier accorde une autorisation au domaine du fichier SWF qui essaie d’accéder à l’objet Bitmap (voir« Contrôles de site Web (fichiers de régulation) » à la page 1095). L’objet LoaderInfo qui correspond au fichier chargé (et à l’objet Loader) inclut les trois propriétés suivantes, qui définissent la relation entre l’objet chargé et l’objet Loader : childAllowsParent, parentAllowsChild et sameDomain.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les événements liés à la liste d’affichage sont soumis à des restrictions d’accès de sécurité en fonction du sandbox de l’objet d’affichage qui distribue l’événement. Un événement de la liste d’affichage traverse des phases de capture et de propagation (voir « Gestion des événements » à la page 129). Au cours de ces deux phases un événement passe de l’objet d’affichage source aux objets d’affichage parent dans la liste d’affichage. Si un objet parent appartient à un sandbox de sécurité différent de celui de l’objet d’affichage source, la phase de capture ou de propagation vers le haut s’arrête en dessous de cet objet parent, sauf si une relation de confiance est établie entre le propriétaire de l’objet parent et celui de l’objet source. Cette confiance mutuelle s’établit des manières suivantes : 1 Le fichier SWF propriétaire de l’objet parent doit appeler la méthode Security.allowDomain() pour approuver
2 Le fichier SWF propriétaire de l’objet source doit appeler la méthode Security.allowDomain() pour approuver
L’objet LoaderInfo qui correspond au fichier chargé (et à l’objet Loader) inclut les deux propriétés suivantes, qui définissent la relation entre l’objet chargé et l’objet Loader : childAllowsParent et parentAllowsChild. Pour les événements distribués à partir d’objets autres que les objets d’affichage, il n’existe aucune vérification de sécurité ni aucune implication liée à la sécurité.
BitmapData.drawWithQuality() et SoundMixer.computeSpectrum(). Par défaut, il est impossible d’obtenir des données de pixels ou des données audio d’objets graphiques ou audio rendus ou lus par un fichier multimédia chargé dans un autre sandbox. Vous disposez toutefois des méthodes suivantes pour accorder un droit d’accès à ces données en franchissant les limites du sandbox :
Ce fichier de régulation doit accorder l’accès au domaine du fichier SWF qui tente d’appeler la méthode BitmapData.draw(), BitmapData.drawWithQuality() ou SoundMixer.computeSpectrum() pour extraire des données de ce fichier. La méthode drawWithQuality est disponible dans Flash Player 11.3 et les versions ultérieures et dans AIR 3.3 et les versions ultérieures. Les sections qui suivent offrent des détails sur l’accès aux données bitmap, son et vidéo.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les méthodes draw() et drawWithQuality() (Flash Player 11.3 et AIR 3.3) d’un objet BitmapData permettent d’extraire les pixels actuellement affichés de tout objet d’affichage vers l’objet BitmapData. Il peut s’agir des pixels d’un objet MovieClip, d’un objet Bitmap ou d’un objet d’affichage. Vous devez remplir les conditions suivantes pour que ces méthodes dessinent des pixels sur l’objet BitmapData :
Si ces conditions ne sont pas réunies, une exception SecurityError est renvoyée. Lorsque vous appelez la méthode load() de la classe Loader, vous pouvez spécifier un paramètre context, qui constitue un objet LoaderContext. Si vous réglez la propriété checkPolicyFile de l’objet LoaderContext sur true, Flash Player recherche un fichier de régulation d’URL sur le serveur à partir duquel l’image est chargée. S’il existe un fichier de régulation autorisant le domaine du fichier SWF à l’origine du chargement, le fichier peut accéder aux données de l’objet Bitmap ; dans le cas contraire, l’accès est refusé. Vous pouvez également spécifier une propriété checkPolicyFile dans une image chargée via la balise <img> d’un champ de texte. Pour plus d’informations, voir « Chargement de fichiers SWF et d’images à l’aide de la balise <img> d’un champ de texte » à la page 1106.
Chaque son est associé à deux types de sandbox, un sandbox de contexte et un sandbox de propriétaire :
Lorsque vous chargez le son à l’aide de la méthode load() de la classe Sound, vous pouvez spécifier un paramètre context, qui constitue un objet SoundLoaderContext. Si vous définissez la propriété checkPolicyFile de l’objet
La méthode SoundMixer.areSoundsInaccessible() vous permet de savoir si l’appel à la méthode SoundMixer.stopAll() n’entraînerait pas l’arrêt de tous les sons parce que le sandbox de l’une ou de plusieurs des
La méthode SoundMixer.stopAll() permet d’arrêter tous les sons dont le sandbox de propriétaire est le même que celui de l’appelant de stopAll(). Elle arrête également les sons dont la lecture a été déclenchée par des fichiers SWF ayant appelé la méthode Security.allowDomain() pour autoriser le domaine du fichier SWF appelant la méthode stopAll(). Tous les autres sons ne sont pas arrêtés ; vous pouvez vérifier leur présence en appelant la méthode SoundMixer.areSoundsInaccessible(). L’appel de la méthode computeSpectrum() demande que chaque son en cours de lecture soit issu du même sandbox que l’objet appelant la méthode ou de la même source qui a autorisé l’accès au sandbox de l’appelant. Autrement, une exception SecurityError est renvoyée. Pour les sons chargés à partir de sons incorporés dans la bibliothèque d’un fichier SWF, l’autorisation est accordée en appelant la méthode Security.allowDomain() dans le fichier SWF chargé. Pour les données audio chargées à partir de sources autres que des fichiers SWF (issues de fichiers mp3 chargés ou de fichiers vidéo), un fichier de régulation d’URL hébergé sur le serveur source doit autoriser l’accès aux données figurant dans le fichier multimédia chargé. Pour plus d’informations, voir « Contrôles de création (développeur) » à la page 1099 et « Contrôles de site Web (fichiers de régulation) » à la page 1095. Pour accéder aux données audio à partir de flux RTMP, vous devez autoriser l’accès au serveur. La propriété ActionScript côté serveur Client.audioSampleAccess permet d’accéder à des répertoires spécifiques de Flash Media Server. Pour plus d’informations, voir le Guide de référence ActionScript de Flash Media Server côté serveur.
Il existe deux types de vidéo :
• La vidéo progressive, chargée à partir d’un fichier FLV ou F4V Pour extraire les graphiques d’exécution de flux RTMP par le biais des méthodes draw, vous devez autoriser l’accès au serveur. La propriété ActionScript côté serveur Client.videoSampleAccess permet d’accéder à des répertoires spécifiques de Flash Media Server. Pour plus d’informations, voir le Guide de référence ActionScript de Flash Media Server côté serveur. Lorsque vous appelez la méthode draw avec la vidéo progressive comme paramètre source, l’appelant de la méthode doit provenir du même sandbox que le fichier FLV ou le serveur du fichier FLV doit contenir un fichier de régulation qui autorise le domaine du fichier SWF appelant. Pour demander le téléchargement du fichier de régulation, définissez la propriété checkPolicyFile de l’objet NetStream sur true.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Un contenu Flash Player et AIR peut échanger des données avec les serveurs. Le chargement de données et le chargement de fichier multimédia sont deux opérations distinctes, car les informations chargées apparaissent sous forme d’objets de programme, au lieu d’être affichées sous forme de fichier multimédia. En règle générale, un contenu peut charger des données issues du même domaine que le domaine d’origine du contenu. Un contenu requiert cependant le plus souvent des fichiers de régulation pour charger les données issues d’autres domaines (voir « Contrôles de site Web (fichiers de régulation) » à la page 1095). Remarque : étant donné qu’un contenu qui s’exécute dans le sandbox d’application AIR n’est jamais transmis à partir d’un domaine distant (sauf si le développeur importe intentionnellement un contenu distant dans le sandbox d’application), il ne peut pas participer aux types d’attaques bloqués par les fichiers de régulation. Un contenu AIR qui réside dans le sandbox d’application est autorisé à charger des données par les fichiers de régulation. Toutefois, un contenu AIR qui réside dans d’autres sandbox est soumis aux restrictions décrites dans cette section.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Vous pouvez charger des données telles que des fichiers XML ou texte. Les méthodes load() des classes URLLoader et URLStream sont régies par les autorisations d’un fichier de régulation d’URL. Si vous utilisez la méthode load() pour charger un contenu issu d’un autre domaine que celui du code qui appelle la méthode, le moteur d’exécution recherche le fichier de régulation d’URL sur le serveur des actifs chargés. S’il existe un fichier de régulation et qu’il autorise l’accès au domaine du contenu à l’origine du chargement, vous pouvez charger les données.
Par défaut, le moteur d’exécution recherche un fichier de régulation socket transmis à partir du port 843. Comme dans le cas des fichiers de régulation d’URL, ce fichier est appelé Fichier de régulation maître. Lors de l’introduction des fichiers de régulation dans Flash Player 6, les fichiers socket n’étaient pas pris en charge. Les connexions aux serveurs socket étaient autorisées par un fichier de régulation figurant à l’emplacement par défaut sur un serveur HTTP à condition d’utiliser le port 80 du même hôte que le serveur socket. Flash Player 9 prend toujours cette fonctionnalité en charge mais ce n’est pas le cas de Flash Player 10. Dans Flash Player 10, seuls les fichiers de régulation socket peuvent autoriser les connexions socket. A l’instar des fichiers de régulation d’URL, les fichiers de régulation socket prennent en charge une instruction de méta-régulation qui identifie les ports dédiés aux fichiers de régulation. La méta-régulation des fichiers de régulation socket est définie sur « all », plutôt que sur « master-only ». Par conséquent, à moins qu’un paramètre plus restrictif soit défini dans le fichier de régulation maître, Flash Player considère comme acquis que n’importe quel socket de l’hôte peut servir un fichier de régulation socket. L’accès aux connexions socket et socket XML est désactivé par défaut, même si le socket auquel vous vous connectez se trouve dans le même domaine que le fichier SWF. Vous pouvez autoriser l’accès de niveau socket en servant un fichier de régulation socket à partir d’un des emplacements suivants :
• Le même port que la connexion socket principale • Un autre port que la connexion socket principale Par défaut, Flash Player recherche un fichier de régulation socket sur le port 843 et sur le même port que la connexion socket principale. Si vous souhaitez servir un fichier de régulation socket à partir d’un autre port, le fichier SWF doit appeler Security.loadPolicyFile(). La syntaxe d’un fichier de régulation socket est identique à celle d’un fichier de régulation d’URL, à la différence qu’elle doit aussi spécifier les ports accessibles. Un fichier de régulation socket servi via un port dont le numéro est inférieur à 1024 peut autoriser l’accès à tous les ports. Un fichier de régulation transmis via le port 1024 ou supérieur ne peut définir l’accès qu’au port 1024 et aux ports supérieurs. Les ports accessibles sont spécifiés par l’attribut to-ports dans la balise <allow-access-from>. Il est possible d’utiliser des numéros de ports, des plages de ports et des caractères génériques. Voici un exemple de fichier de régulation socket : <?xml version="1.0"?> <!DOCTYPE cross-domain-policy SYSTEM "http://www.adobe.com/xml/dtds/cross-domain-policy.dtd"> <!-- Policy file for xmlsocket://socks.mysite.com --> Si vous implémentez un serveur socket et que vous devez fournir un fichier de régulation socket, vous devez choisir entre fournir le fichier de régulation sur le port qui accepte les connexions principales et utiliser un autre port. Dans les deux cas, votre serveur doit attendre la première transmission en provenance de votre client avant d’envoyer une réponse. Lorsque Flash Player demande un fichier de régulation, il transmet toujours la chaîne suivante dès que la connexion est établie : <policy-file-request/>
N’envisagez pas d’utiliser la même connexion pour la requête de fichier de régulation et pour la connexion principale. Vous devez fermer la connexion une fois le fichier de régulation transmis. A défaut, Flash Player ferme la connexion du fichier de régulation, puis établit une autre connexion pour la connexion principale.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour protéger les données contre toute écoute ou modification lorsqu’elles transitent via Internet, vous disposez des protocoles TLS (Transport Layer Security) et SSL (Socket Layer Security) sur le serveur d’origine des données. Vous pouvez ensuite établir une connexion au serveur via le protocole HTTPS. Dans les applications destinées à AIR 2 ou ultérieur, vous pouvez également protéger les communications socket TCP. La classe SecureSocket permet de lancer une connexion socket à un serveur socket qui utilise TLS version 1 or SSL version 4.
Il se produit un envoi de données lorsque le code envoie des données à un serveur ou une ressource. L’envoi de données est systématiquement autorisé si le contenu est issu d’un domaine du réseau. Un fichier SWF local peut envoyer des données à des adresses réseau uniquement si elles se trouvent dans le sandbox approuvé localement, le sandbox local avec accès au réseau ou le sandbox d’application AIR. Pour plus d’informations, voir « Sandbox locaux » à la page 1087. Vous pouvez utiliser la fonction flash.net.sendToURL() pour envoyer des données à une URL. D’autres méthodes permettent d’envoyer des requêtes aux URL. Il s’agit notamment des méthodes de chargement, telles que Loader.load() et Sound.load(), et des méthodes de chargement de données, telles que URLLoader.load() et URLStream.load().
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures La méthode FileReference.upload() lance le chargement d’un fichier sélectionné par l’utilisateur vers un serveur distant. Vous devez appeler la méthode FileReference.browse() ou FileReferenceList.browse() avant la méthode FileReference.upload(). Le code qui lance la méthode FileReference.browse() ou FileReferenceList.browse() ne peut être appelé qu’en réponse à un événement de souris ou de clavier. S’il est appelé dans d’autres situations, Flash Player 10 et les versions ultérieures renvoie une exception. Un événement lancé par l’utilisateur n’est toutefois pas nécessaire pour appeler ces méthodes à partir du sandbox d’application AIR. L’appel de la méthode FileReference.download() ouvre une boîte de dialogue dans laquelle l’utilisateur peut télécharger un fichier à partir d’un serveur distant. Remarque : si votre serveur nécessite une authentification des utilisateurs, seuls les fichiers SWF s’exécutant dans un navigateur (c’est-à-dire utilisant le plug-in du navigateur ou un contrôle ActiveX) peuvent fournir une boîte de dialogue pour demander à l’utilisateur un nom et un mot de passe d’authentification, ceci uniquement pour les téléchargements. Flash Player ne permet pas de charger des fichiers sur un serveur qui nécessite une authentification utilisateur. Les chargements et téléchargements ne sont autorisés que si le fichier SWF appelant appartient au sandbox local avec système de fichiers. Par défaut, un fichier SWF ne peut pas lancer un chargement ou un téléchargement avec un serveur autre que le sien. Il peut le faire si le serveur en question fournit un fichier de régulation accordant un accès au domaine du fichier SWF appelant.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lorsque vous chargez un fichier SWF, vous pouvez définir le paramètre context de la méthode load() de l’objet Loader utilisé pour le chargement. Ce paramètre prend un objet LoaderContext. Si vous réglez la propriété securityDomain de cet objet LoaderContext sur Security.currentDomain, Flash Player recherche un fichier de régulation d’URL sur le serveur à partir duquel le fichier SWF est chargé. S’il en existe un qui autorise l’accès au domaine du fichier SWF à l’origine du chargement, vous pouvez charger le fichier SWF sous forme de média importé. De cette manière, le fichier à l’origine du chargement obtient l’accès aux objets de la bibliothèque du fichier SWF. Une autre méthode permet d’autoriser l’accès d’un fichier SWF aux classes des fichiers SWF chargés à partir d’un autre sandbox de sécurité : le fichier SWF chargé doit simplement appeler la méthode Security.allowDomain() pour autoriser l’accès du domaine du fichier SWF appelant. Cet appel à la méthode Security.allowDomain() peut s’ajouter à la méthode constructeur de la classe principale du fichier SWF chargé. Ensuite, le fichier SWF à l’origine du chargement doit ajouter un écouteur d’événement pour répondre à l’événement init distribué par la propriété contentLoaderInfo de l’objet Loader. Cet événement est distribué lorsque le fichier SWF chargé a appelé la méthode Security.allowDomain() dans la méthode constructeur et que des classes du fichier SWF chargé sont disponibles pour le fichier SWF à l’origine du chargement. Le fichier SWF en cours de chargement peut extraire les classes du fichier SWF chargé en appelant Loader.contentLoaderInfo.applicationDomain.getDefinition() ou Loader.contentLoaderInfo.applicationDomain.getQualifiedDefinitionNames() (Flash Player 11.3 et les versions ultérieures et AIR 3.3 et les versions ultérieures).
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Dans Flash Player 6, le domaine utilisé par certains paramètres Flash Player dépend de la fin du domaine du fichier SWF. Il s’agit notamment des paramètres d’autorisations relatifs à la caméra et au microphone, aux quotas de stockage et au stockage d’objets partagés persistants. Si le domaine du fichier SWF comprend plus de deux segments, par exemple www.example.com, le premier segment du domaine (www) est supprimé et la fin du domaine est exploitée. Ainsi, dans Flash Player 6, www.exemple.com et magasin.exemple.com ont en commun le domaine « example.com » pour ces paramètres. De même, www.exemple.co.fr et magasin.exemple.co.fr ont tous les deux recours au domaine exemple.co.fr pour ces paramètres. Cette caractéristique pose problème pour les fichiers SWF issus de domaines distincts, tels que example1.co.uk et example2.co.uk, qui ont alors accès aux mêmes objets partagés. A compter de Flash Player 7, les paramètres du lecteur sont choisis par défaut en fonction du domaine exact d’un fichier SWF. Par exemple, le fichier SWF de www.exemple.com applique les paramètres du lecteur de www.exemple.com, et le fichier SWF de magasin.exemple.com utiliserait les paramètres différents de magasin.exemple.com. Dans le cas d’un fichier SWF écrit en ActionScript 3.0, si Security.exactSettings conserve la valeur par défaut true, Flash Player utilise les domaines exacts pour les paramètres de lecteur. Si sa valeur est false, Flash Player utilise les paramètres de domaine de Flash Player 6. Si vous modifiez la valeur de exactSettings, vous devez le faire avant que ne survienne tout événement obligeant Flash Player à choisir des paramètres de lecteur (par exemple l’utilisation d’une caméra ou d’un microphone, ou l’extraction d’un objet partagé persistant).
Ils peuvent toutefois s’exécuter dans des applications distinctes. Ainsi, un fichier SWF qui s’exécute dans un navigateur, un fichier SWF qui s’exécute en mode Projection et une application AIR peuvent tous communiquer par le biais de la classe LocalConnection. A chaque communication LocalConnection correspond un émetteur et un récepteur. Par défaut, Flash Player permet les communications LocalConnection si le code s’exécute dans le même domaine. Si le code s’exécute dans des sandbox distincts, le récepteur doit accorder une autorisation à l’émetteur à l’aide de la méthode LocalConnection.allowDomain(). La chaîne passée comme argument à la méthode LocalConnection.allowDomain() peut contenir n’importe lesquels des éléments suivants : noms de domaine exacts, adresses IP et caractère générique *. Le format de la méthode allowDomain() n’est plus le même que dans ActionScript 1.0 et 2.0. Dans ces versions, allowDomain était une méthode de rappel que vous implémentiez. Dans ActionScript 3.0, allowDomain() est une méthode intégrée de la classe LocalConnection que vous appelez. Le fonctionnement de la nouvelle version de allowDomain() est semblable à celui de Security.allowDomain(). Un fichier SWF peut utiliser la propriété domain de la classe LocalConnection pour déterminer le domaine.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Les API suivantes gèrent la génération de scripts et l’accès URL externes (par le biais d’URL HTTP, de mailto:, etc.) :
• La méthode ExternalInterface.call() • La fonction flash.net.navigateToURL() Si un contenu est chargé à partir du système de fichiers local, les appels à ces méthodes n’aboutissent que si le code et la page Web qui le contient (le cas échéant) se trouvent dans le sandbox approuvé localement ou le sandbox d’application AIR. Ils échouent si le contenu provient du sandbox local avec accès au réseau ou local avec système de fichiers. Si le contenu n’est pas chargé localement, toutes ces API peuvent communiquer avec la page Web à laquelle elles sont intégrées, selon la valeur du paramètre AllowScriptAccess décrit ci-dessous. La fonction flash.net.navigateToURL() peut en outre communiquer avec toute fenêtre ou tout cadre de navigateur ouvert, pas seulement avec la page contenant le fichier SWF. Pour plus d’informations à ce sujet, voir « Utilisation de la fonction navigateToURL() » à la page 1119.
Le paramètre AllowScriptAccess prend en charge trois valeurs : "always", "sameDomain" et "never".
HTML à laquelle il est intégré, même s’il ne provient pas du même domaine qu’elle.
AllowScriptAccess pour empêcher un fichier SWF d’un domaine d’accéder à un script sur une page HTLM issue d’un autre domaine.
Elle n’est pas recommandée et elle ne devrait pas s’avérer nécessaire si vous ne servez pas de fichiers SWF non approuvés à partir de votre propre domaine. Si vous devez envoyer des fichiers SWF non approuvés, Adobe vous conseille de créer un sous-domaine distinct et d’y placer l’ensemble du contenu non approuvé. L’exemple suivant illustre le réglage de la balise AllowScriptAccess dans une page HTML pour autoriser l’accès URL externe à un autre domaine : <object id='MyMovie.swf' classid='clsid:D27CDB6E-AE6D-11cf-96B8-444553540000' codebase='http://download.adobe.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,0,0' height='100%' width='100%'> <param name='AllowScriptAccess' value='always'/> <param name='src' value=''MyMovie.swf'/> Pour les instructions de programmation, telles que navigateToURL("javascript: alert('Hello from Flash Player.')"), les règles suivantes s’appliquent :
• Si la cible est la page HTML à laquelle le fichier SWF est intégré, les règles allowScriptAccess décrites plus haut s’appliquent.
• Si la cible contient du contenu issu d’un autre domaine que le fichier SWF et qu’aucune des deux conditions précédentes n’est remplie, la requête échoue.
• La cible correspond à un des mots clés spéciaux "_top" ou "_parent" • Le fichier SWF se trouve dans une page Web hébergée dans un domaine différent et
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Pour plus d’informations sur l’accès URL externe, voir les sections suivantes du manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash :
• Méthode call() de la classe ExternalInterface • Fonction flash.net.navigateToURL() Le fichier SWF peut utiliser le paramètre localPath des méthodes SharedObject.getLocal() et SharedObject.getRemote() afin d’exploiter un magasin d’objets partagés associé à une partie de son URL seulement. Ainsi, le fichier SWF peut autoriser le partage avec d’autres fichiers SWF issus d’autres URL. Même si la valeur transmise au paramètre localPath est '/' , celle-ci spécifie tout de même un magasin d’objets partagés propres à son domaine. Les utilisateurs peuvent limiter l’accès aux objets partagés via la boîte de dialogue Paramètres de Flash Player ou via le Gestionnaire des paramètres. Par défaut, le volume d’objets partagés créés ne peut dépasser 100 Ko de données par domaine. Les administrateurs et les utilisateurs peuvent également limiter la capacité à écrire dans le système de fichiers. Pour plus d’informations, voir « Contrôles administrateur » à la page 1092 et « Contrôles utilisateur » à la page 1093.
Le choix du magasin d’objets partagé dépend de l’URL d’origine du fichier SWF. Cela reste vrai même dans les deux cas de figure où un fichier SWF ne provient pas d’une URL simple : importation et chargement dynamique. L’importation s’applique lorsque vous chargez un fichier SWF dont la propriété LoaderContext.securityDomain a la valeur SecurityDomain.currentDomain. Dans ce cas, le fichier SWF chargé portera une pseudo-URL qui commence par le domaine du fichier SWF à l’origine du chargement, puis spécifie sa véritable URL d’origine. Le chargement dynamique renvoie au chargement d’un fichier SWF à l’aide de la méthode Loader.loadBytes(). Dans cette situation, le fichier SWF chargé porte une pseudo-URL qui commence par l’URL complète du fichier SWF à l’origine du chargement, suivie d’un entier d’identification. Dans les deux cas de figure (importation et chargement dynamique), la pseudo-URL du fichier SWF peut être analysée à l’aide de la propriété LoaderInfo.url. Cette pseudoURL est traitée comme une URL réelle pour définir le magasin d’objets partagés. Elle peut être utilisée en partie ou dans son intégralité comme paramètre localPath d’un objet partagé. Les utilisateurs et les administrateurs peuvent choisir de désactiver l’utilisation d’objets partagés tiers. Il s’agit des objets partagés utilisés par tout fichier SWF exécuté dans un navigateur Web lorsque l’URL d’origine de ce fichier SWF est d’un domaine différent de l’URL affichée dans la barre d’adresse du navigateur. Les administrateurs et utilisateurs peuvent choisir de désactiver l’utilisation des objets partagés tiers pour des raisons de confidentialité, s’ils souhaitent éviter la surveillance inter-domaines. Pour éviter cette restriction, il est judicieux de veiller à ce que tous les fichiers SWF utilisant des objets partagés soient chargés uniquement dans une structure de pages HTML qui garantit que le fichier provient du même domaine que celui affiché dans la barre d’adresse du navigateur. Si vous essayez d’utiliser des objets partagés à partir d’un fichier SWF tiers et que l’utilisation des objets partagés tiers est désactivée, les méthodes SharedObject.getLocal() et SharedObject.getRemote() renvoient la valeur null. Pour plus d’informations, voir les adresses www.adobe.com/fr/products/flashplayer/articles/thirdpartylso.
Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures Lorsqu’un fichier SWF essaie d’accéder à la caméra ou au microphone de l’utilisateur à l’aide de la méthode Camera.get() ou Microphone.get(), Flash Player affiche une boîte de dialogue de confidentialité, dans laquelle l’utilisateur peut autoriser ou refuser l’accès à sa caméra ou son microphone. L’utilisateur et l’administrateur peuvent également désactiver l’accès à la caméra de manière globale ou pour chaque site, grâce aux commandes du fichier mms.cfg, de l’interface de paramétrage et du Gestionnaire des paramètres (voir « Contrôles administrateur » à la page 1092 et « Contrôles utilisateur » à la page 1093). Si des restrictions utilisateur s’appliquent, les méthodes Camera.get() et Microphone.get() renvoient chacune la valeur null. La propriété Capabilities.avHardwareDisable vous permet de déterminer si l’administrateur a interdit (valeur true) ou autorisé (valeur false) la caméra et le microphone. La méthode System.setClipboard() autorise un fichier SWF à remplacer le contenu du Presse-papiers par une chaîne de caractères en texte brut, ce qui ne pose aucun risque de sécurité. Pour éviter que les mots de passe et autres données sensibles ne soient coupés ou copiés dans le Presse-papiers, il n’existe pas de méthode getClipboard() correspondante. Une application qui s’exécute dans Flash Player peut uniquement contrôler les événements de clavier et de souris qui se produisent dans son focus. un contenu qui s’exécute dans Flash Player ne peut pas détecter d’événements de clavier ou de souris dans une autre application.
Les applications AIR s’exécutent dotées des mêmes restrictions de sécurité que les applications natives. En règle générale, les applications AIR, à l’instar des applications natives, disposent d’un accès étendu aux fonctionnalités du système d’exploitation, telles que la lecture et l’écriture de fichiers, le démarrage d’applications, les dessins sur l’écran et la communication avec le réseau. Les restrictions du système d’exploitation qui se rapportent aux applications natives, tels que les privilèges spécifiques aux utilisateurs, se rapportent également aux applications AIR. Bien que le modèle de sécurité d’Adobe® AIR® constitue une évolution par rapport à celui d’Adobe® Flash® Player, le contrat de sécurité est différent de celui appliqué au contenu d’un navigateur. Ce contrat offre aux développeurs des moyens sûrs pour accéder à des fonctions beaucoup plus importantes et se lancer dans des expériences beaucoup plus enrichissantes et variées qui ne conviendraient pas à une application basée sur un navigateur. Les applications AIR sont rédigées à l’aide de pseudo-code binaire compilé (contenu SWF) ou de script interprété (JavaScript, HTML) de sorte que le moteur d’exécution fournisse la gestion de la mémoire. Ceci minimise les risques que les applications AIR soient affectées par des vulnérabilités liées à la gestion de la mémoire, comme une surcharge de mémoire tampon ou une détérioration de mémoire. Voilà quelques-unes des vulnérabilités les plus courantes qui affectent les applications d’ordinateur de bureau rédigées en code natif.
Les applications AIR sont distribuées par le biais des fichiers du programme d’installation AIR, dotés de l’extension air ou via des programmes d’installation natifs, dotés du format de fichier et de l’extension de la plate-forme native. Ainsi, le format du programme d’installation natif de Windows correspond à EXE, tandis que le format natif d’Android est APK. Lorsqu’Adobe AIR est installé et qu’un fichier d’installation AIR est ouvert, le moteur d’exécution d’AIR gère le processus d’installation. Si un programme d’installation natif est utilisé, c’est le système d’exploitation qui gère le processus d’installation. Remarque : les développeurs peuvent spécifier une version, un nom d’application et une source d’éditeur lors de l’utilisation du format de fichier AIR, mais le flux initial de l’installation de l’application lui-même ne peut pas être modifié. Cette restriction est tout à l’avantage des utilisateurs car toutes les applications AIR partagent une procédure d’installation sûre, continue et stable, gérée par le moteur d’exécution. Si une personnalisation de l’application s’avère nécessaire, cela peut se faire lors de sa première exécution.
Adobe AIR 1.0 et les versions ultérieures Pour les applications AIR qui font appel au format de fichier AIR, il est nécessaire d’installer préalablement le moteur d’exécution sur l’ordinateur d’un utilisateur, de même qu’il est nécessaire d’installer en premier lieu le module d’extension du navigateur Flash Player pour les fichiers SWF. Le moteur d’exécution est installé à l’emplacement suivant sur un ordinateur de bureau :
• Windows : C:\Program Dernière mise à jour le 27/4/2013
Adobe AIR 1.0 et les versions ultérieures Le modèle de sécurité AIR permet aux utilisateurs de décider s’il y a lieu d’installer une application AIR. L’expérience dans l’installation d’AIR a permis d’apporter plusieurs améliorations par rapport aux technologies d’installation des applications natives, ce qui rend cette décision de confiance plus facile à prendre pour les utilisateurs :
En règle générale, les utilisateurs ne devraient pas installer d’application d’ordinateur de bureau qui provient d’une source à laquelle ils ne font pas confiance ou qui ne peut pas être authentifiée. Le fardeau de la preuve sur la sécurité pour les applications natives est également valable pour les applications AIR comme elle l’est pour d’autres applications à installer.
Adobe AIR 1.0 et les versions ultérieures Le répertoire d’installation peut être défini à l’aide de l’une des deux options suivantes : 1 L’utilisateur personnalise la destination au cours de l’installation. L’application s’installe à l’emplacement que lui
2 Si celui-ci ne modifie pas la destination de l’installation, l’application s’installe suivant le chemin par défaut fourni
Le processus d’installation pour les applications AIR copie tous les fichiers que le développeur a inclus au sein du fichier d’installation d’AIR dans l’ordinateur local de l’utilisateur. L’application installée est composée des éléments suivants :
Une application AIR est exécutée par :
Le système des fichiers d’application contient aussi des sous-répertoires liés à la fonction de l’application. Par exemple, les informations envoyées à la mémoire locale chiffrée sont enregistrées dans un sous-répertoire qui porte le même nom que l’identifiant d’application de l’application.
Les applications AIR disposent de privilèges pour écrire dans n’importe quel emplacement du disque dur de l’utilisateur ; toutefois, il est recommandé aux développeurs d’utiliser le chemin app-storage:/ pour le stockage local lié à leur application. Les fichiers écrits dans app-storage:/ à partir d’une application se trouvent à un emplacement standard qui dépend de leur système d’exploitation :
• AIR 3.2 et les versions ultérieures - <appData>/<appId>/Local
/Utilisateurs/<user>/Bibliothèque/Préférences
Le développement et le déploiement des mises à jour des logiciels constituent l’un des défis les plus importants dans le domaine de la sécurité auxquels sont confrontées les applications rédigées en code natif. L’interface de programmation AIR fournit un mécanisme pour améliorer cette situation : la méthode Updater.update() peut être appelée lors du lancement afin de vérifier un emplacement distant pour un fichier AIR. Si une mise à jour s’impose, le fichier AIR est téléchargé, installé et l’application redémarre. Les développeurs peuvent utiliser cette classe, non seulement pour obtenir de nouvelles fonctions, mais également pour réagir à des risques de sécurité potentiels. La classe Updater est réservée à la mise à jour des applications distribuées sous forme de fichiers AIR. Les applications distribuées en tant qu’applications natives doivent utiliser les fonctions de mise à jour éventuellement intégrées au système d’exploitation natif. Remarque : les développeurs peuvent spécifier la version d’une application en paramétrant la propriété versionNumber du fichier descripteur d’application.
La suppression d’une application AIR entraîne celle de tous les fichiers de son répertoire. Elle ne supprime toutefois pas tous les fichiers que l’application a éventuellement écrits hors de ce répertoire. Les changements apportés à des fichiers par l’application AIR hors du répertoire de l’application ne sont pas affectés par une suppression des applications AIR.
Adobe AIR 1.0 et les versions ultérieures Sous Windows, les administrateurs peuvent configurer une machine pour empêcher (ou permettre) les mises à jour de l’installation de l’application AIR et du moteur d’exécution. Ces paramètres se trouvent dans le Registre Windows sous la clé suivante : HKLM\Software\Policies\Adobe\AIR. Parmi eux figurent : Paramètre du Registre
Le SDK d’AIR intègre trois classes de rendu du contenu HTML. La classe HTMLLoader assure une intégration étroite entre le code JavaScript et les API d’AIR. La classe StageWebView est une classe de rendu HTML et son intégration à l’application AIR hôte est extrêmement réduite. Le contenu chargé par la classe StageWebView n’est jamais placé dans le sandbox de sécurité de l’application et il lui est impossible d’accéder aux données ou d’appeler des fonctions dans l’application AIR hôte. Sur les platesformes de poste de travail, la classe StageWebView fait appel au moteur HTML AIR intégré, basé sur Webkit, qui est également utilisé par la classe HTMLLoader. Sur les plates-formes mobiles, elle fait appel au contrôle HTML fourni par le système d’exploitation. Par conséquent, sur les plates-formes mobiles, la classe StageWebView est soumise aux mêmes considérations de sécurité et souffre des mêmes vulnérabilités que le navigateur Web du système. La classe TextField peut afficher des chaînes de texte HTML. Il est impossible d’exécuter du code JavaScript, mais le texte peut inclure des liens et des images chargées en externe. Pour plus d’informations, voir la section « Contournement des erreurs JavaScript liées à la sécurité » à la page 1021.
Comme HTML dans AIR conserve son organisation normale, basée sur des pages, l’environnement HTML est intégralement actualisé si l’image supérieure de votre contenu HTML « navigue » dans une page différente. Vous pouvez utiliser des images et des iframes pour maintenir la persistance des données dans AIR pratiquement de la même façon que vous le feriez pour une application Web qui s’exécuterait dans un navigateur. Définissez les principaux objets de votre application dans l’image supérieure et ils persisteront aussi longtemps que vous n’autoriserez pas l’image à naviguer dans une nouvelle page. Utilisez des images ou des iframes enfant pour charger et afficher des parties transitoires de l’application. Il existe plusieurs façons de maintenir la persistance des données, en plus des images ou bien à leur place. Par exemple, des cookies, des objets locaux partagés, l’emplacement de stockage des fichiers locaux, celui des fichiers chiffrés et celui des bases de données locales. Comme HTML dans AIR conserve sa frontière normale et imprécise entre le code exécutable et les données, AIR place le contenu de l’image supérieure de l’environnement HTML dans le sandbox de l’application. Après l’événement load de la page, AIR restreint toutes les opérations, telles que eval(), susceptibles de convertir une chaîne de texte en un objet exécutable. Cette restriction est imposée même lorsqu’une application ne charge pas du contenu distant. Pour que du contenu HTML distant puissent exécuter ces opérations restreintes, vous devez utiliser des images ou des iframes pour placer le contenu dans un sandbox hors application. (L’exécution de contenu dans une image enfant affectée à un sandbox peut s’avérer nécessaire lorsque vous utilisez des structures d’application JavaScript qui reposent sur la fonction eval().) Pour un répertoire complet des restrictions relatives à JavaScript dans le sandbox de l’application, voir la section « Restrictions relatives au code pour un contenu dans des sandbox différents » à la page 1130. Comme HTML dans AIR conserve sa capacité à charger du contenu distant et possiblement non sécurisé, AIR applique une politique de « même origine » qui empêche le contenu d’un domaine d’interagir avec celui de l’autre. Pour permettre une interaction entre contenu de l’application et contenu d’un autre domaine, vous pouvez configurer un pont qui servira d’interface entre une image parent et une image enfant. Configuration d’un rapport de sandbox parent-enfant Adobe AIR 1.0 et les versions ultérieures AIR ajoute les attributs sandboxRoot et documentRoot aux éléments image et iframe de HTML. Ces attributs vous permettent de traiter le contenu de l’application comme s’il provenait d’un autre domaine : Attribut
Dernière mise à jour le 27/4/2013
Chaque pont ne va que dans une seule direction : childSandboxBridge : la propriété childSandboxBridge permet à l’image enfant de présenter une interface au
} interface.storeID = "abc" window.childSandboxBridge = interface;
//write text to file Si le contenu enfant tente de définir une propriété de l’objetparentSandboxBridge, le moteur d’exécution renvoie une exception SecurityError. Si le contenu parent tente de définir une propriété de l’objetchildSandboxBridge, le moteur d’exécution renvoie une exception SecurityError.
Comme nous l’avons vu dans l’introduction à cette rubrique, « Sécurité HTML dans Adobe AIR » à la page 1127, le moteur d’exécution applique les règles et fournit des mécanismes pour compenser les vulnérabilités de sécurité possibles dans HTML et JavaScript. La présente rubrique répertorie ces restrictions. Si le code tente d’appeler ces interfaces de programmation réservées, le moteur d’exécution renvoie une erreur accompagnée du message « Violation des règles de sécurité dans le sandbox de sécurité de l’application par le moteur d’exécution d’Adobe AIR sur du code JavaScript ». Pour plus d’informations, voir la section « Contournement des erreurs JavaScript liées à la sécurité » à la page 1021. Restrictions relatives à l’utilisation de la fonction eval() de JavaScript et de techniques similaires Adobe AIR 1.0 et les versions ultérieures Pour le contenu HTML dans le sandbox de sécurité de l’application, il existe des limites dans l’utilisation des interfaces de programmation susceptibles de transformer dynamiquement les chaînes en code exécutable après le chargement de ce code (après que l’événement onload de l’élément body a été distribué et que l’exécution de la fonction du gestionnaire onload est terminée). Ceci empêche l’application d’injecter (et d’exécuter) du code par inadvertance à partir de sources non-applicatives, comme des domaines du réseau potentiellement non sécurisés. Par exemple, si votre application utilise des données de chaîne à partir d’une source distante pour écrire dans la propriété innerHTML d’un élément DOM, la chaîne pourrait inclure du code exécutable (JavaScript) et susceptible d’exécuter des opérations non sécurisées. Toutefois, tant que le contenu est en cours de chargement, il n’y a pas de risque que des chaînes distantes soient insérées dans le DOM. L’utilisation de la fonction eval() de JavaScript constitue une restriction. Dès que le code du sandbox de l’application est chargé et après le traitement du gestionnaire d’événement onload, vous ne pouvez utiliser la fonction eval() que dans certaines conditions. Les règles suivantes s’appliquent dans l’utilisation de la fonction eval() après le chargement du code à partir du sandbox de sécurité de l’application :
• Les définitions de fonctions sont interdites. • Le paramétrage de toute propriété est interdit. • Les littéraux de fonctions sont interdits.
Un code généré dynamiquement, comme celui qui est produit par l’appel de la fonction eval(), présenterait un risque pour la sécurité s’il était autorisé au sein du sandbox de l’application. Par exemple, une application peut exécuter par inadvertance une chaîne chargée à partir d’un domaine de réseau et celle-ci peut contenir du code malveillant. Par exemple, il peut s’agir de code conçu pour la suppression ou la modification de fichiers dans l’ordinateur de l’utilisateur. Ou bien encore de code qui renvoie à un domaine de réseau non approuvé une copie du contenu d’un fichier local. Vous trouverez ci-dessous des façons de générer du code dynamique :
• Utilisation des propriétés innerHTML ou des fonctions DOM pour insérer des balises de script qui chargent un script hors du répertoire de l’application.
• Utilisation de la fonction setInterval() ou setTimout(), où le premier paramètre (qui définit la fonction pour qu’elle s’exécute de façon asynchrone) est une chaîne (à évaluer) plutôt qu’un nom de fonction (comme dans setTimeout('x = 4', 1000)).
Le code dans le sandbox de sécurité de l’application ne peut utiliser ces méthodes au cours du chargement du contenu. Ces restrictions n’empêchent pas l’utilisation d’eval() avec des littéraux d’objet JSON. Ceci permet au contenu de votre application de travailler avec la bibliothèque JavaScript de JSON. Il vous est néanmoins interdit d’utiliser du code JSON surchargé (avec des gestionnaires d’événement). Pour d’autres structures Ajax et bibliothèques de code JavaScript, assurez-vous que le code de la structure ou de la bibliothèque fonctionne sur du code généré dynamiquement, dans le cadre de ces restrictions. Si ce n’est pas le cas, placez tout contenu qui utilise la structure ou la bibliothèque dans un sandbox de sécurité hors application. Pour plus d’informations, voir « Restrictions associées au contenu JavaScript dans AIR » à la page 1089 et « Programmation entre contenu d’application et contenu hors application » à la page 1139. Adobe maintient un répertoire de structures Ajax, reconnues pour leur prise en charge du sandbox de sécurité de l’application, à l’adresse http://www.adobe.com/products/air/develop/ajax/features/. Contrairement au contenu du sandbox de sécurité de l’application, celui de JavaScript dans un sandbox de sécurité hors application peut à tout moment appeler la fonction eval() pour exécuter dynamiquement le code généré.
à la page 1139. Restrictions relatives à l’utilisation des appels XMLHttpRequest Adobe AIR 1.0 et les versions ultérieures Le contenu HTML du sandbox de sécurité de l’application utilise des méthodes XMLHttpRequest pour charger des données à partir d’emplacements hors du sandbox de l’application au cours du chargement du contenu HTML et de l’exécution de l’événement onLoad. Par défaut, un contenu HTML dans des sandbox de sécurité hors application n’est pas autorisé à utiliser l’objet XMLHttpRequest de JavaScript pour charger des données à partir des domaines autres que le domaine qui appelle la requête. Une balise image ou iframe peut contenir un attribut allowcrosscomainxhr. La définition de cet attribut sur toute valeur non nulle permet au contenu de l’image ou de l’iframe d’utiliser l’objet XMLHttpRequest de JavaScript pour charger les données à partir de domaines autres que celui du code qui appelle la requête. <iframe id="UI" src="http://example.com/ui.html" sandboxRoot="http://example.com/" allowcrossDomainxhr="true" documentRoot="app:/"> </iframe>
Restrictions relatives au chargement d’éléments de CSS, d’image, d’iframe et d’img (pour un contenu dans des sandbox hors application) Adobe AIR 1.0 et les versions ultérieures Un contenu HTML dans un sandbox de sécurité distant (réseau) ne peut charger que du contenu CSS, image, iframe et img à partir de sandbox distants (à partir d’URL du réseau). Un contenu HTML dans un sandbox local avec système de fichiers, local avec réseau ou approuvé localement ne peut charger que du contenu CSS, image, iframe et img à partir de sandbox locaux (mais pas à partir de sandbox d’application ou distants).
Si une fenêtre créée par un appel à la méthode window.open() de JavaScript affiche un contenu à partir d’un sandbox de sécurité hors application, le titre de la fenêtre commence par celui de la fenêtre principale (de lancement), suivi du caractère deux points (:). Il n’est pas possible d’utiliser du code pour retirer cette partie du titre de l’écran. Le contenu d’un sandbox de sécurité hors application ne peut réussir un appel à la méthode window.open() de JavaScript que s’il répond à un événement déclenché par la souris ou le clavier de l’utilisateur. Cette condition permet d’éviter qu’un contenu hors application ne crée des fenêtres qui pourraient être utilisées de façon trompeuse, par exemple pour des attaques d’hameçonnage. En outre, le gestionnaire d’événement pour l’événement de la souris ou du clavier ne peut pas paramétrer la méthode window.open() pour qu’elle s’exécute au bout d’un certain temps, par exemple en appelant la fonction setTimeout(). Le contenu d’un sandbox distant (réseau) ne peut utiliser la méthode window.open() que pour ouvrir le contenu dans un sandbox de réseau distant. Il ne peut pas utiliser cette méthode pour ouvrir du contenu à partir de l’application ou d’un sandbox local. Un contenu de sandbox local avec système de fichiers, sandbox local avec réseau ou sandbox approuvé localement (voir « Sandbox de sécurité » à la page 1087) ne fait appel à la méthode window.open() que pour ouvrir un contenu dans un sandbox local. Il ne peut pas utiliser cette méthode pour ouvrir du contenu à partir de l’application ou d’un sandbox distant. Erreurs lors de l’appel de code interdit Adobe AIR 1.0 et les versions ultérieures Si vous appelez du code interdit d’exécution dans un sandbox en raison de ces restrictions liées à la sécurité, le moteur d’exécution distribue une erreur JavaScript : « Violation des règles de sécurité dans le sandbox de sécurité de l’application par le moteur d’exécution d’Adobe AIR sur du code JavaScript ». Pour plus d’informations, voir la section « Contournement des erreurs JavaScript liées à la sécurité » à la page 1021.
Adobe AIR 1.0 et les versions ultérieures La méthode loadString() de la classe HTMLLoader vous permet de créer du contenu HTML au moment de l’exécution. Toutefois, les données utilisées comme contenu HTML peuvent être corrompues lorsqu’elles sont chargées à partir d’une source Internet non sécurisée. De ce fait, par défaut, le contenu HTML créé à l’aide de la méthode loadString() n’est pas placé dans le sandbox de l’application et n’a pas accès aux API AIR. Vous pouvez cependant définir la propriété placeLoadStringContentInApplicationSandbox d’un objet HTMLLoader sur true pour placer le contenu HTML créé avec la méthode loadString() dans le sandbox de l’application. Pour plus d’informations, voir la section « Chargement de contenu HTML depuis une chaîne » à la page 1020.
Adobe AIR 1.0 et les versions ultérieures Les applications AIR disposent de privilèges spéciaux lorsqu’elles sont installées. Il est essentiel que les mêmes privilèges ne soient pas dévoilés à un autre contenu, y compris les fichiers distants et les fichiers locaux qui ne font pas partie de l’application.
• Le code dans le sandbox de sécurité de l’application ne peut pas autoriser l’accès aux autres sandbox par un appel à la méthode Security.allowDomain(). L’appel à cette méthode depuis le sandbox de sécurité de l’application renvoie une erreur.
Il subsiste encore des situations où l’application AIR principale demande un contenu à partir du domaine distant pour avoir un accès contrôlé à des scripts de celle-ci, ou vice-versa. Pour ce faire, le moteur d’exécution fournit un mécanisme de pont de sandbox qui sert de passerelle entre deux sandbox. Un pont de sandbox peut fournir une interaction explicite entre sandbox de sécurité distant et d’application. Le pont de sandbox présente deux objets auxquels les scripts chargés et en cours de chargement peuvent tous deux accéder :
Ce sont les valeurs et non les références qui sont transmises par le pont de sandbox. Toutes les données sont sérialisées. Ce qui signifie que les objets présentés par l’un des côtés du pont ne peuvent pas être définis par l’autre et qu’aucun des objets présentés n’est typé. De plus, vous ne pouvez présenter que des objets et des fonctions simples (pas complexes). Si le contenu enfant tente de définir une propriété de l’objetparentSandboxBridge, le moteur d’exécution renvoie une exception SecurityError. De même, si le contenu parent tente de définir une propriété de l’objetchildSandboxBridge, le moteur d’exécution renvoie une exception SecurityError.
Adobe AIR 1.0 et les versions ultérieures Supposez qu’une application de disquaire AIR souhaite autoriser des fichiers distants à diffuser le prix des albums, mais qu’il ne souhaite pas que le fichier SWF distant dévoile s’il s’agit d’un prix de vente. Pour ce faire, une classe StoreAPI fournit une méthode d’acquisition de prix tout en masquant le prix de vente. Une occurrence de cette classe StoreAPI est alors affectée à la propriété parentSandboxBridge de l’objet LoaderInfo dont l’objet Loader charge le fichier SWF distant. Voici le code pour le disquaire AIR :
Dans un contenu HTML, les propriétés parentSandboxBridge et childSandboxBridge sont ajoutées à l’objet Window de JavaScript d’un document enfant. Pour un exemple sur la façon de configurer des fonctions de pont dans un contenu HTML, voir la section « Configuration d’une interface de pont de sandbox » à la page 1040.
Adobe AIR 1.0 et les versions ultérieures Lorsque vous présentez des ponts de sandbox, il est important de présenter des interfaces de programmation de haut niveau qui limitent le degré d’exposition à des abus. Nous vous rappelons que le contenu qui appelle votre implémentation de pont peut être en danger (par exemple, par une injection de code). Ainsi, par exemple, la présentation de la méthode readFile(path:String) (qui lit le contenu d’un fichier arbitraire) par un pont est exposé à un risque. Il serait préférable de présenter une interface de programmation readApplicationSetting() qui ne suit pas un chemin mais qui lit un fichier spécifique. L’approche plus sémantique limite les dommages qu’une application peut causer dès qu’une de ses parties est affectée.
« Programmation croisée du contenu dans des sandbox de sécurité distincts » à la page 1038 « Sandbox de l’application AIR » à la page 1088
Adobe AIR 1.0 et les versions ultérieures Les applications qui s’exécutent dans un navigateur Web n’ont qu’une interaction limitée avec le système de fichiers local de l’utilisateur. Les navigateurs Web implémentent des stratégies de sécurité qui garantissent que l’ordinateur de l’utilisateur ne peut pas être mis en danger à la suite du chargement d’un contenu du Web. Par exemple, les fichiers SWF qui passent par Flash Player dans un navigateur ne peuvent pas interagir directement avec des fichiers qui se trouvent déjà sur l’ordinateur d’un utilisateur. Les objets partagés et les cookies peuvent être écrits dans l’ordinateur d’un utilisateur dans le but de maintenir les préférences et les données de l’utilisateur, mais il s’agit là de la limite de l’interaction avec le système de fichiers. Comme les applications AIR sont installées en mode natif, ils possèdent un contrat de sécurité différent, celui qui inclut la possibilité de lire et d’écrire dans tout le système de fichiers local. Cette liberté s’accompagne d’une grande responsabilité de la part des développeurs. Les insécurités accidentelles de l’application compromettent non seulement la fonctionnalité de l’application, mais aussi l’intégrité de l’ordinateur de l’utilisateur. C’est pourquoi les développeurs devraient lire la section « Recommandations destinées aux développeurs en matière de sécurité » à la page 1140. Les développeurs AIR peuvent accéder à des fichiers du système de fichiers local et en placer dans ce système à l’aide de plusieurs conventions de modèles d’URL :
A moins qu’il n’existe des restrictions de l’administrateur à propos de l’ordinateur de l’utilisateur, les applications AIR détiennent le privilège d’écrire sur tout emplacement du disque dur de l’utilisateur. Les développeurs sont informés d’utiliser le chemin app-storage:/ pour le stockage local lié à leur application. Les fichiers écrits sur app-storage:/ à partir d’une application sont placés dans un emplacement standard :
/Utilisateurs/<utilisateur>/Bibliothèque/Preferences
C:\Documents and Settings\<nom d'utilisateur>\Application Data
Adobe AIR 1.0 et les versions ultérieures Les applications AIR limitent la programmation de l’accès au contenu hors application de façon plus rigoureuse que le module d’extension du navigateur de Flash Player ne le fait pour du contenu non approuvé. Par exemple, dans le Flash Player du navigateur, lorsqu’un fichier SWF affecté au sandbox approuvé localement appelle la méthode System.allowDomain(), la programmation de l’accès est autorisée à tout SWF chargé à partir du domaine spécifié. L’approche analogue à partir du contenu de l'application dans les applications AIR n’est pas permise, car cela consisterait à autoriser un accès déraisonnable au fichier hors application dans le système de fichiers de l’utilisateur. Les fichiers distants ne peuvent pas accéder directement au sandbox de l’application, quels que soient les appels à la méthode Security.allowDomain().
L’avantage que peut présenter un pont de sandbox est très bien décrit par un exemple. Supposez qu’une application de disquaire AIR souhaite fournir une interface de programmation à des publicitaires voulant créer leurs propres fichiers SWF qui leur permettront de communiquer avec l’application du disquaire. Celui-ci veut fournir aux publicitaires des méthodes pour rechercher des artistes et des CD du magasin. Mais il veut aussi isoler quelques méthodes et propriétés du fichier SWF tiers, pour des raisons de sécurité. Cette possibilité existe avec un pont de sandbox. Par défaut, un contenu chargé de l’extérieur dans une application AIR à l’exécution n’a accès à aucune méthode ou propriété de l’application principale. Avec une implémentation de pont de sandbox personnalisé, un développeur peut fournir des services au contenu distant sans exposer ces méthodes et propriétés. Considérez le pont de sandbox comme une voie entre contenu approuvé et non approuvé qui fournit une communication entre le contenu chargé et le contenu récepteur sans présenter de références d’objet. Pour plus d’informations sur la façon d’utiliser les ponts de sandbox en toute sécurité, voir la section « Programmation entre contenus de différents domaines » à la page 1133.
Adobe AIR 1.0 et les versions ultérieures La méthode Loader.loadBytes() fournit un moyen pour une application de générer un contenu SWF à partir d’un tableau d’octets. Cependant, des attaques par injection sur des données chargées à partir de sources distantes pourraient causer des dommages sérieux lors du chargement du contenu. Ceci est particulièrement valable lors du chargement des données dans le sandbox de l’application où le contenu SWF généré peut accéder à l’ensemble des interfaces de programmation d’AIR au complet. Il existe des conditions légitimes pour utiliser la méthode loadBytes() sans générer de code SWF exécutable. Vous pouvez utiliser cette méthode pour générer des données d’image afin de contrôler le délai d’affichage de celle-ci, par exemple. Il y a aussi des situations légitimes qui dépendent effectivement de l’exécution du code, comme la création dynamique de contenu SWF pour de la lecture audio. Dans AIR, par défaut, la méthode loadBytes() ne vous permet pas de charger un contenu SWF ; il ne vous permet que de charger un contenu d’image. Dans AIR, la propriété loaderContext de la méthode loadBytes() possède une propriété allowLoadBytesCodeExecution que vous pouvez définir sur true afin d’autoriser explicitement l’application à utiliser loadBytes() pour charger un contenu SWF exécutable. Le code ci-dessous montre comment utiliser cette fonction : var loader:Loader = new Loader(); var loaderContext:LoaderContext = new LoaderContext(); loaderContext.allowLoadBytesCodeExecution = true; loader.loadBytes(bytes, loaderContext);
Adobe AIR 1.0 et les versions ultérieures Bien que les applications AIR soient créées à l’aide des technologies du Web, il est important pour les développeurs de noter qu’ils ne travaillent pas au sein du sandbox de sécurité du navigateur. Ceci signifie qu’il est possible de créer des applications qui n’endommagent pas le système local, intentionnellement ou non. AIR tente de minimiser ce risque, mais il y a toujours moyen d’introduire des vulnérabilités. La présente rubrique décrit les risques potentiels en matière de sécurité.
Adobe AIR 1.0 et les versions ultérieures Les fichiers qui existent dans le répertoire de l’application sont affectés au sandbox de l’application et ils disposent des privilèges du moteur d’exécution au complet. Les applications qui écrivent dans le système de fichiers local devraient plutôt écrire dans app-storage:/. Ce répertoire est distinct des fichiers d’application puisqu’il se trouve sur l’ordinateur de l’utilisateur. De ce fait, les fichiers n’étant pas affectés au sandbox de l’application, ils présentent un risque réduit en matière de sécurité. Il est recommandé aux développeurs de tenir compte des éléments suivants :
• N’incluez un fichier de programmation dans un fichier AIR (de l’application installée) que si son comportement est bien compris et approuvé.
Adobe AIR 1.0 et les versions ultérieures Une application AIR court un risque lors de l’utilisation de données ou de contenu externes. C’est pourquoi il faut prendre grand soin lors de l’utilisation de données qui proviennent du réseau ou du système de fichiers. C’est en fin de compte le développeur qui est responsable de la fiabilité des connexions réseau établies. Le chargement de données étrangères est toutefois risqué par nature et ne devrait pas être utilisé dans le cadre d’opérations critiques. Les mises en garde suivantes s’adressent aux développeurs :
• Utilisation de données provenant d’une source du réseau pour créer une URL à laquelle l’application fait appel pour envoyer des informations de nature privée
• Si les informations d’identification doivent être stockées localement, chiffrez-les lorsque vous écrivez dans le système de fichiers local. Le moteur d’exécution fournit, par la classe EncryptedLocalStore, un emplacement de stockage unique pour chaque application installée Pour plus d’informations, voir « Stockage local chiffré » à la page 737.
Adobe AIR 1.0 et les versions ultérieures Au cours de l’installation de l’application, le moteur d’exécution s’assure qu’une version de l’application n’est pas actuellement installée. Si elle l’est déjà, le moteur d’exécution compare la chaîne de la version à la version en cours d’installation. S’il y a une différence, l’utilisateur peut choisir de mettre à niveau son installation. Le moteur d’exécution ne peut pas garantir que la version nouvellement installée soit plus récente que la précédente, seulement qu’elle est différente. Un attaquant peut distribuer une version antérieure à l’utilisateur pour contourner une faiblesse dans la sécurité. C’est pourquoi il est recommandé au développeur de vérifier la version lorsque l’application est exécutée. Il est également utile que les applications vérifient le réseau pour des mises à jour. Ainsi, même si un attaquant parvient à faire exécuter une version antérieure à un utilisateur, celle-ci se rendra compte qu’elle a besoin d’une mise à jour. De plus, la mise en place d’un modèle de contrôle des versions de l’application clair complique la tâche d’un attaquant qui vise à convaincre un utilisateur d’installer une version antérieure.
Adobe AIR 1.0 et les versions ultérieures Tous les fichiers du programme d’installation AIR sont tenus de contenir du code signé. La signature du code est un processus cryptographique qui confirme que l’origine spécifiée du logiciel est exacte. Une application AIR peut être signée par le biais d’un certificat délivré par une autorité de certification externe (CA) ou d’un certificat auto-signé que vous créez vous-même. Un certificat commercial délivré par une AC bien connue est fortement recommandé. Il garantit à vos utilisateurs qu’ils installent votre application et non pas une contrefaçon. Il est cependant possible de créer des certificats auto-signés à l’aide d’adt à partir du kit SDK ou à l’aide de Flash, Flash Builder ou toute autre application qui utilise adt pour la génération de certificats. Les certificats auto-signés ne garantissent pas l’intégrité de l’application en cours d’installation et devraient être réservés aux tests d’applications réalisés avant la commercialisation de ces dernières.
Sur Android, comme pour tout autre périphérique, AIR se conforme au modèle de sécurité natif. AIR gère par ailleurs ses propres règles de sécurité, qui ont pour objet de faciliter la programmation d’applications connectées à Internet sécurisées. Etant donné que les applications AIR sur Android utilisent le format de package Android, l’installation relève du modèle de sécurité d’Android. Le programme d’installation des applications AIR n’est pas utilisé. Le modèle de sécurité d’Android s’articule autour de trois éléments fondamentaux :
• Signatures d’application ACCESS_FINE_LOCATION Permet à l’application d’accéder aux données GPS via la classe Geolocation. ACCESS_NETWORK_STATE et ACCESS_WIFI_STATE Permet à l’application d’accéder aux informations du réseau via la
CAMERA Permet à l’application d’accéder à la caméra. INTERNET Permet à l’application d’effectuer des requêtes réseau. Permet également de procéder au débogage à
READ_PHONE_STATE Permet au moteur d’exécution d’AIR de désactiver l’audio lorsqu’il se produit un appel entrant. RECORD_AUDIO Permet à l’application d’accéder au microphone. WAKE_LOCK et DISABLE_KEYGUARD Permet à l’application d’empêcher le périphérique d’entrer en mode de veille à
WRITE_EXTERNAL_STORAGE Permet à l’application d’écrire sur la carte mémoire externe du périphérique.
Tous les packages d’application destinés à la plate-forme Android doivent impérativement être signés. Etant donné que les applications AIR sur Android sont mises en package au format APK Android natif, elles sont signées conformément aux conventions Android, plutôt qu’aux conventions AIR. Bien qu’Android et AIR utilisent la signature de code de manière similaire, il existe des différences non négligeables :
• Deux applications signées par le même certificat peuvent spécifier un ID partagé qui les autorise à accéder aux fichiers de données et au cache de l’autre application. (Ce type de partage n’est pas géré par AIR. ) ID utilisateur d’application Android utilise un noyau Linux. A chaque application installée est affecté un ID utilisateur de type Linux, qui détermine ses droits pour des opérations telles que l’accès aux fichiers. Les fichiers stockés dans les répertoires d’application, de stockage d’application et les répertoires temporaires sont protégés par des droits de système de fichiers. Les fichiers écrits dans un emplacement de stockage externe (en d’autres termes, la carte SD) peuvent être lus, modifiés et supprimés par d’autres applications ou par l’utilisateur lorsque la carte SD est montée en tant que périphérique de stockage de masse sur un ordinateur. Les cookies associés aux requêtes Internet ne sont pas partagés entre applications AIR. Confidentialité de l’image d’arrière-plan Lorsqu’un utilisateur fait passer une application en arrière-plan, certaines versions d’Android effectuent une capture d’écran qu’elles utilisent comme miniature dans la liste des applications récentes. Cette capture d’écran est stockée dans la mémoire du périphérique et tout attaquant qui contrôle physiquement ce dernier peut y accéder. Si l’application affiche des informations confidentielles, celles-ci ne doivent pas figurer sur la capture d’écran d’arrièreplan. L’événement deactivate distribué par l’objet NativeApplication indique qu’une application est sur le point de passer en arrière-plan. Effacez ou masquez toute information confidentielle à l’aide de cet événement.
Android : Security and Permissions Il est possible d’utiliser la classe EncryptedLocalStore pour enregistrer les données, mais celles-ci ne sont pas chiffrées sur les périphériques Android. Le modèle de sécurité d’Android repose sur l’ID utilisateur de l’application pour protéger les données des autres applications. Les applications qui utilisent un ID utilisateur partagé et qui sont signées avec le même certificat de signature de code font appel au même magasin local chiffré. Important : sur un téléphone associé à une racine, toute application s’exécutant avec des privilèges racines peut accéder aux fichiers d’autres applications. Les données enregistrées à l’aide du magasin local chiffré ne sont donc pas sécurisées sur un périphérique associé à une racine.
Lorsqu’une application passe en arrière-plan sous iOS, le système d’exploitation effectue une capture d’écran permettant d’animer la transition. Cette capture d’écran est stockée dans la mémoire du périphérique et tout attaquant qui contrôle physiquement ce dernier peut y accéder. Si l’application affiche des informations confidentielles, celles-ci ne doivent pas figurer sur la capture d’écran d’arrièreplan. L’événement deactivate distribué par l’objet NativeApplication indique qu’une application est sur le point de passer en arrière-plan. Effacez ou masquez toute information confidentielle à l’aide de cet événement.
ActionScript 3.0. Vous pouvez recourir aux exemples de diverses façons, en fonction des périphériques que vous utilisez ou ciblez. Ordinateurs exécutant Flash Professional ou Flash Builder Voir « Exécution d’exemples ActionScript 3.0 dans Flash
ActionScript 3.0. Utilisez les instructions trace et d’autres outils de débogage pour mieux comprendre le fonctionnement d’un exemple de code. Périphériques mobiles Vous pouvez exécuter les exemples de code ActionScript 3.0 sur des périphériques mobiles qui prennent en charge Flash Player 10.1 et les versions ultérieures. Voir « Exécution d’exemples ActionScript 3.0 sur un périphérique mobile » à la page 1150. Vous pouvez par ailleurs exécuter ces exemples sur votre ordinateur à l’aide de Flash Professional ou de Flash Builder. Périphériques TV Bien que vous ne puissiez pas exécuter ces exemples sur des périphériques TV, vous pouvez en tirer parti en les exécutant sur votre ordinateur. Voir Flash Platform for TV sur le site Web Adobe Developer Connection pour plus d’informations sur le développement d’applications pour périphériques TV.
Les types d’exemples de code ActionScript 3.0 sont les suivants :
• Exemples basés sur les classes (principalement dans le Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash)
Exemples de type fragment de code Un exemple de type fragment de code se présente comme suit : var x:int = 5; trace(x); // 5
Exemples basés sur les classes De nombreux exemples illustrent le code source associé à une classe ActionScript entière. Un exemple basé sur une classe se présente comme suit :
Utilisation des exemples de code ActionScript
} • Un ou plusieurs fichiers MXML à utiliser avec Flash Builder • Des fichiers de données, d’image et de son ou autres actifs utilisés par l’exemple d’application (facultatifs) Ces exemples sont le plus souvent livrés sous forme de fichiers d’archives ZIP. Liste des exemples du guide du développeur dans le fichier ZIP Le fichier ZIP pour Flash Professional CS5 et Flex 4 (à télécharger depuis www.adobe.com/go/learn_programmingAS3samples_flash_fr) contient les exemples suivants :
• AlgorithmicVisualGenerator (« Exemple d’utilisation de l’API de dessin : générateur algorithmique d’effets visuels » à la page 241)
• CapabilitiesExplorer (« Exemple d’utilisation de Capabilities : détection des capacités du système » à la page 906) • CustomErrors (« Exemple de gestion des erreurs : application CustomErrors » à la page 72) • DisplayObjectTransformer (« Exemple de géométrie : application d’une transformation de matrice à un objet d’affichage » à la page 226)
• GlobalStockTicker (« Exemple : Internationalisation d’une application de suivi des stocks » à la page 991) • IntrovertIM_HTML (« Exemple d’API externe : communications entre ActionScript et JavaScript dans un navigateur Web » à la page 882)
• PlayList (« Exemple de tableau : PlayList » à la page 49) • PodcastPlayer (« Exemple d’objet Sound : Podcast Player » à la page 482) • ProjectionDragger (« Exemple : Projection de perspective » à la page 369) • ReorderByZ (« Réorganisation de l’affichage à l’aide d’objets Matrix3D » à la page 374) • RSSViewer (« Utilisation de XML dans un exemple ActionScript : chargement de données RSS depuis Internet » à la page 118)
De nombreux articles de démarrage rapide figurant dans le Centre des développeurs Flash et Flex comportent également des exemples pratiques.
Professional Appliquez l’une des procédures suivantes (selon le type d’exemple) pour exécuter un exemple à l’aide de Flash Professional. Exécution d’un exemple de fragment de code dans Flash Professional Pour exécuter un exemple de fragment de code dans Flash Professional : 1 Choisissez Fichier > Nouveau. 2 Dans la boîte de dialogue Nouveau document, sélectionnez Document Flash et cliquez sur OK.
3 Cliquez sur la première image du premier calque dans le panneau Scénario. 4 Dans le panneau Actions, saisissez ou collez l’exemple de fragment de code. 5 Choisissez Fichier > Enregistrer. Attribuez un nom au fichier et cliquez sur OK. 6 Pour tester l’exemple, sélectionnez Contrôle > Tester l’animation.
Pour exécuter un exemple basé sur une classe dans Flash Professional : 1 Sélectionnez Fichier > Nouveau. 2 Dans la boîte de dialogue Nouveau document, sélectionnez un fichier ActionScript, puis cliquez sur OK. Une
3 Copiez l’exemple de code basé sur une classe et collez-le dans la fenêtre d’édition.
//... } correspondre au nom du fichier source ActionScript que vous venez d’enregistrer (ExempleMenuContextuel, par exemple). 8 Sélectionnez Fichier > Enregistrer. Attribuez au fichier FLA le nom de la classe stipulée dans l’exemple (tel
9 Pour tester l’exemple, sélectionnez Contrôle > Tester l’animation. 3 Accédez au dossier où vous avez désarchivé le fichier ZIP. Sélectionnez le fichier FLA dans ce dossier, puis cliquez
4 Pour tester l’exemple, sélectionnez Contrôle > Tester l’animation.
Builder Appliquez l’une des procédures suivantes (selon le type d’exemple) pour exécuter un exemple à l’aide de Flash Builder. Exécution d’un exemple de fragment de code dans Flash Builder Pour exécuter un exemple de fragment de code dans Flash Builder : 1 Créez un projet Flex (en sélectionnant File > New > Flex Project) ou créez une application MXML dans un projet
2 Dans le fichier MXML généré, ajoutez une balise <mx:Script>. 3 Collez le contenu de l’exemple de fragment de code entre les balises <mx:Script> et </mx:Script>. Enregistrez le
Pour exécuter un exemple basé sur une classe dans Flash Builder : 1 Sélectionnez File > New > ActionScript Project. 2 Entrez le nom de la classe principale (ExempleMenuContextuel, par exemple) dans le champ Project Name. Utilisez
Finish pour créer le projet et le principal fichier ActionScript. 3 Effacez tout contenu généré du fichier ActionScript. Collez l’exemple de code, y compris les instructions de package
Remarque : certains exemples basés sur les classes, tels que l’exemple de la classe flashx.textLayout.container.ContainerController, comprennent plusieurs niveaux dans la déclaration du package (package flashx.textLayout.container.examples {). Pour ces exemples, enregistrez le fichier dans un sousdossier qui doit correspondre à la déclaration du package (flashx/textLayout/container/examples) ou supprimez le nom du package (afin qu’ActionScript démarre avec le package { uniquement) pour tester le fichier depuis n’importe quel emplacement. 4 Pour exécuter l’exemple, sélectionnez l’option de menu Run > Run associée au nom de la classe ActionScript
Exécution d’un exemple pratique dans Flash Builder Les exemples pratiques sont le plus souvent livrés sous forme de fichiers d’archives ZIP. Pour exécuter un exemple pratique dans Flash Builder : 1 Désarchivez le fichier ZIP dans le dossier de votre choix. Attribuez au dossier un nom descriptif tel
2 Dans Flash Builder, sélectionnez File > New Flex Project. Dans la section Project Location, cliquez sur Browse et
(ExempleMenuContextuel, par exemple). Utilisez les valeurs par défaut des autres champs ou modifiez-les en fonction de l’environnement en vigueur. Cliquez sur Next pour poursuivre la procédure. 3 Dans le panneau Output, cliquez sur Next pour accepter la valeur par défaut. 4 Dans le panneau Source Paths, cliquez sur le bouton Browse en regard du champ Main Application File.
5 Pour exécuter l’exemple, sélectionnez l’option de menu Run > Run associée au principal fichier MXML (Run > Run
Vous pouvez exécuter des exemples de code ActionScript 3.0 sur un périphérique mobile qui prend en charge Flash Player 10.1. Ceci dit, cette opération a généralement pour objet d’apprendre à utiliser des classes et méthodes déterminées. Dans ce cas de figure, exécutez l’exemple sur un périphérique non mobile tel qu’un ordinateur de bureau. L’ordinateur de bureau permet de faire appel à des instructions de suivi et autres outils de débogage Flash Professional ou Flash Builder pour se familiariser avec un exemple de code. Pour exécuter l’exemple sur un périphérique mobile, copiez les fichiers correspondant sur ce dernier ou sur un serveur Web. Pour copier les fichiers sur le périphérique et exécuter l’exemple dans le navigateur, procédez comme suit : 1 Créez le fichier SWF en vous référant aux instructions stipulées dans « Exécution d’exemples ActionScript 3.0 dans
Dans Flash Professional, vous créez le fichier SWF par le biais de Contrôle > Tester l’animation. Dans Flash Builder, vous créez le fichier SWF lors de l’exécution, du débogage ou de la création du projet Flash Builder. 2 Copiez le fichier SWF dans un répertoire du périphérique mobile. Utilisez à cet effet le logiciel fourni avec le
3 Dans la barre d’adresse du navigateur sur le périphérique mobile, entrez la chaîne « file:// URL » associée au fichier
Pour copier les fichiers sur un serveur Web et exécuter l’exemple dans le navigateur du périphérique, procédez comme suit : 1 Créez un fichier SWF et un fichier HTML. Commencez par suivre les instructions figurant dans « Exécution
2 Copiez les fichiers SWF et HTML dans un répertoire hébergé sur le serveur Web. 3 Dans la barre d’adresse du navigateur du périphérique mobile, entrez l’adresse HTTP du fichier HTML. Entrez par
Avant d’exécuter un exemple sur un périphérique mobile, tenez compte des considérations suivantes. Taille de la scène La taille de scène activée lorsque vous exécutez un exemple sur un périphérique mobile est considérablement inférieure à la taille en vigueur sur un périphérique non mobile. De nombreux exemples ne nécessitent pas une taille de scène spécifique. Lorsque vous créez le fichier SWF, stipulez une taille de scène adaptée au périphérique (176 x 208 pixels, par exemple). Les exemples pratiques figurant dans le Guide du développeur d’Adobe ActionScript 3.0 ont pour objet d’illustrer divers concepts et classes ActionScript 3.0. Tant au niveau présentation qu’au niveau fonctionnement, leur interface utilisateur est adaptée à un ordinateur de bureau ou un ordinateur portable. Bien que les exemples fonctionnent sur un périphérique mobile, la taille de la scène et la conception de l’interface utilisateur ne conviennent pas à un écran de taille réduite. Adobe recommande d’exécuter les exemples pratiques sur un ordinateur pour se familiariser avec le code ActionScript, puis d’utiliser des fragments de code appropriés dans les applications mobiles.
Lorsque vous exécutez un exemple sur un périphérique mobile, il est impossible de visualiser le résultat des instructions de suivi correspondantes. Pour visualiser le résultat, créez une occurrence de la classe TextField. Ajoutez ensuite le texte issu des instructions de suivi à la fin de la propriété text du champ de texte. La fonction suivante permet de définir un champ de texte à des fins de suivi : function createTracingTextField(x:Number, y:Number, width:Number, height:Number):TextField { var tracingTF:TextField = new TextField(); tracingTF.x = x; tracingTF.y = y; tracingTF.width = width; tracingTF.height = height; // A border lets you more easily see the area the text field covers. tracingTF.border = true; // Left justifying means that the right side of the text field is automatically // resized if a line of text is wider than the width of the text field. De nombreux exemples font appel aux champs de texte pour illustrer un concept. Régler la taille du contenu d’un champ de texte optimise parfois sa lisibilité sur un périphérique mobile. Ainsi, si un exemple fait appel à une occurrence de champ de texte appelée myTextField, le code suivant permet de modifier la taille du contenu :
L’interface utilisateur de nombreux exemples est par ailleurs adaptée à un ordinateur de bureau ou un ordinateur portable. Ainsi, la plupart des exemples pratiques figurant dans le Guide du développeur d’ActionScript 3.0 sont conçus pour être visualisés sur un ordinateur de bureau. De ce fait, il est parfois impossible d’afficher la scène dans son intégralité sur l’écran d’un périphérique mobile. Les fonctionnalités de défilement du contenu du navigateur varient selon ce dernier. En outre, les exemples ne sont pas conçus pour capturer et traiter les événements de défilement horizontal ou vertical. L’interface utilisateur de certains exemples n’est de ce fait pas adaptée à un écran de petite taille. Adobe recommande d’exécuter les exemples sur un ordinateur pour se familiariser avec le code ActionScript, puis d’utiliser des fragments de code appropriés dans les applications mobiles. Pour plus d’informations, voir « Défilement horizontal ou vertical des objets d’affichage » à la page 185. Gestion du focus Certains exemples nécessitent l’attribution du focus à un champ. Vous pouvez ainsi entrer du texte ou sélectionner un bouton. Pour ce faire, faites appel au périphérique de pointage du périphérique mobile, tel un stylet ou le doigt. Vous disposez également des touches de navigation du périphérique mobile pour attribuer le focus à un champ. Pour sélectionner un bouton doté du focus, utilisez la touche de sélection du périphérique mobile à l’instar de la touche Entrée sur un ordinateur. Sur certains périphériques, il suffit de taper deux fois sur un bouton pour le sélectionner. Pour plus d’informations sur le focus, voir « Gestion de la cible d’action » à la page 575. Gestion des événements de souris De nombreux exemples écoutent les événements de souris. Sur un ordinateur, ces événements de souris se produisent, par exemple, lorsqu’un utilisateur survole un objet d’affichage ou clique sur un objet d’affichage à l’aide de la souris. Sur un périphérique mobile, les événements issus de périphériques de pointage tels qu’un stylet ou un doigt portent le nom d’événements tactiles. Flash Player 10.1 mappe les événements tactiles sur les événements de souris. Ce mappage assure le fonctionnement du contenu SWF développé avant Flash Player 10.1. Par conséquent, les exemples fonctionnent lorsque l’utilisateur sélectionne ou fait glisser un objet d’affichage à l’aide d’un périphérique de pointage. Performances La puissance de traitement d’un périphérique mobile est inférieure à celle d’un ordinateur de bureau. Certains exemples qui sollicitent intensivement l’unité centrale risquent de s’exécuter lentement sur un périphérique mobile. Ainsi, l’exemple figurant dans « Exemple d’utilisation de l’API de dessin : générateur algorithmique d’effets visuels » à la page 241 effectue un grand nombre d’opérations de calcul et de dessin à chaque image. L’exécution de cet exemple sur un ordinateur illustre diverses API de dessin. L’exemple n’est toutefois pas adapté à certains périphériques mobiles, en raison de leurs performances limitées. Pour plus d’informations sur les performances d’une application sur un périphérique mobile, voir Optimisation des performances pour la plate-forme Adobe Flash.
Chaque base de données est stockée dans son intégralité dans un seul fichier. Un développeur peut spécifier l’emplacement de stockage du fichier de base de données dans le système de fichiers et une application AIR unique peut accéder à une ou plusieurs bases de données (en d’autres termes, à des fichiers de base de données distincts). Ce document présente la syntaxe SQL et la prise en charge des types de données pour les bases de données SQL locales Adobe AIR. Ce document n’a pas pour objectif de servir de référence SQL complète, mais de décrire les détails spécifiques du langage SQL pris en charge par Adobe AIR. Le moteur d’exécution prend en charge la plupart des éléments du langage SQL standard SQL-92. Au vu du nombre de références, sites Web, manuels et supports de formation consacrés à l’apprentissage de SQL, ce document n’a pas pour objectif d’être une référence ou un didacticiel SQL complet. Il se concentre plutôt sur la syntaxe SQL gérée par AIR, ainsi que sur les différences entre SQL-92 et le langage SQL pris en charge. Conventions utilisées dans les définitions d’instruction SQL Les conventions suivantes sont utilisées dans les définitions des instructions du présent document :
• MAJUSCULES : les mots-clés SQL littéraux sont écrits en majuscules. • minuscules : les noms de clause et les termes d’espaces réservés sont écrits en minuscules. • Caractères de définition • ::= indique une définition de clause ou d’instruction. • Caractères de regroupement et de remplacement • | Le caractère pipe est utilisé entre les diverses options gérées et peut être lu comme « ou ». • [] Les éléments placés entre crochets sont des éléments facultatifs ; les crochets peuvent contenir un seul élément ou un ensemble d’éléments gérés.
• () Une paire de parenthèses renfermant une seule clause ou un seul élément indique que les parenthèses sont des caractères littéraux obligatoires.
Les listes de syntaxe SQL suivantes sont prises en charge par le moteur de base de données SQL d’Adobe AIR. Elles sont divisées en explications de divers types d’instructions et de clauses, d’expressions, de fonctions intégrées et d’opérateurs. Les sujets suivants sont passés en revue :
• Instructions de manipulation des données (SELECT, INSERT, UPDATE et DELETE) • Instructions de définition des données (CREATE, ALTER et instructions DROP associées aux tables, aux index, aux vues et aux déclencheurs)
• Fonctions intégrées (fonctions d’agrégation, fonctions scalaires et fonctions de formatage de la date et de l’heure) • Opérateurs • Paramètres • Fonctions SQL non prises en charge SQL le sont, et les opérations de comparaison et de tri respectent parfois la casse, selon les spécifications de la séquence de classement définie pour une colonne ou une opération. Pour plus d’informations, voir COLLATE. Espace blanc Un caractère espace blanc (espace, tabulation, nouvelle ligne, etc.) doit séparer chaque mot dans une
Les instructions de manipulation des données sont les instructions SQL les plus courantes. Ces instructions sont utilisées pour récupérer, ajouter, modifier et supprimer des données dans des tables de bases de données. Les instructions de manipulation de données suivantes sont prises en charge : SELECT, INSERT, UPDATE et DELETE.
La requête est exécutée sur une ou plusieurs tables spécifiées après le mot-clé FROM. Si plusieurs noms de table sont séparés par des virgules, la requête utilise alors la jointure croisée des différentes tables. La syntaxe JOIN permet également de spécifier le mode de jointure des tables. L’unique type de jointure externe pris en charge est LEFT OUTER JOIN. L’expression de clause ON dans les éléments join-arg doit donner une valeur booléenne. Une sousrequête placée entre parenthèses peut être utilisée comme table dans la clause FROM. La clause FROM peut être omise dans sa totalité, auquel cas le résultat est une ligne unique composée des valeurs de la liste d’expressions. La clause WHERE permet de restreindre le nombre de lignes récupérées par la requête. Les expressions de clause WHERE doivent donner une valeur booléenne. Un filtrage des clauses WHERE étant effectué avant tout regroupement, les expressions de la clause WHERE risquent de ne pas inclure de fonction d’agrégation. La clause GROUP BY combine une ou plusieurs lignes du résultat en une ligne de résultat unique. Une clause GROUP BY se révèle particulièrement utile lorsque le résultat contient des fonctions d’agrégation. Les expressions de la clause GROUP BY ne doivent pas nécessairement apparaître dans la liste d’expressions SELECT. La clause HAVING est similaire à la clause WHERE, car elle limite le nombre de lignes renvoyées par l’instruction. La clause HAVING est toutefois appliquée après l’exécution d’un regroupement spécifié par une clause GROUP BY. Par conséquent, l’expression HAVING peut faire référence aux valeurs qui incluent des fonctions d’agrégation. Une expression de clause HAVING ne doit pas obligatoirement apparaître dans la liste SELECT. Telle une expression WHERE, une expression HAVING doit donner une valeur booléenne.
Chaque expression de tri peut éventuellement être suivie d’une clause sort-order composée du mot-clé COLLATE et du nom d’une fonction de classement utilisée pour organiser le texte et/ou du mot-clé ASC ou DESC pour spécifier l’ordre de tri (croissant ou décroissant). Vous pouvez omettre la clause sort-order, auquel cas l’ordre par défaut (croissant) est utilisé. Pour consulter une définition de la clause COLLATE et des fonctions de classement, voir COLLATE. La clause LIMIT définit le nombre maximal de lignes de résultat renvoyées. Une clause LIMIT négative indique qu’il n’existe pas de limite supérieure. Le mot-clé OFFSET facultatif qui suit la clause LIMIT spécifie le nombre de lignes à ignorer au début du jeu de résultats. Dans une requête SELECT composée, la clause LIMIT peut n’apparaître qu’après l’instruction SELECT finale, et la limite s’applique à l’ensemble de la requête. Notez que si le mot-clé OFFSET est utilisé dans la clause LIMIT, la limite correspond au premier nombre entier et le décalage au second nombre entier. Si une virgule est utilisée au lieu du mot-clé OFFSET, le décalage correspond au premier nombre et la limite au second nombre. Cette contradiction apparente est intentionnelle, car elle assure une compatibilité accrue avec les systèmes de bases de données SQL hérités. Une instruction SELECT composée est constituée de plusieurs instructions SELECT simples connectées par l’un des opérateurs UNION, UNION ALL, INTERSECT ou EXCEPT. Dans une instruction SELECT composée, toutes les instructions SELECT constituantes doivent spécifier le même nombre de colonnes de résultats. Une seule clause ORDER BY doit suivre l’instruction SELECT finale (et précéder l’unique clause LIMIT si elle est spécifiée). Les opérateurs UNION et UNION ALL combinent les résultats des instructions SELECT précédentes et suivantes dans une même table. Avec l’opérateur UNION, toutes les lignes de résultat sont distinctes, alors qu’avec l’opérateur UNION ALL, il peut exister des doublons. L’opérateur INTERSECT prend l’intersection des résultats des instructions SELECT précédentes et suivantes. L’opérateur EXCEPT prend le résultat de l’instruction SELECT précédente après avoir supprimé les résultats de l’instruction SELECT suivante. Lorsque trois instructions SELECT ou plus sont connectées dans une instruction composée, elles sont groupées de la première à la dernière. Pour consulter une définition des expressions autorisées, voir Expressions. Depuis AIR 2.5, l’opérateur SQL CAST est pris en charge en lecture pour convertir des données BLOB en objets ActionScript ByteArray. Par exemple, le code suivant lit les données brutes qui ne sont pas stockées au format AMF et les stocke dans un objet ByteArray : stmt.text = "SELECT CAST(data AS ByteArray) AS data FROM pictures;"; stmt.execute(); var result:SQLResult = stmt.getResult(); var bytes:ByteArray = result.data[0].data;
INSERT [OR conflict-algorithm] INTO [database-name.] table-name [(columnlist)] select-statement La première forme (qui contient le mot-clé VALUES) crée une ligne unique dans une table existante. Si aucun élément column-list n’est spécifié, le nombre de valeurs doit correspondre au nombre de colonnes de la table. Si un élément column-list est spécifié, le nombre de valeurs doit correspondre au nombre de colonnes spécifié. Les colonnes de la table qui n’apparaissent pas dans la liste de colonnes sont remplies avec les valeurs par défaut définies lors de la création de la table ou avec NULL si aucune valeur par défaut n’est définie. La seconde forme de l’instruction INSERT extrait ses données d’une instruction SELECT. Le nombre de colonnes du résultat de l’instruction SELECT doit correspondre exactement au nombre de colonnes de la table si aucun élément column-list n’est spécifié, ou au nombre de colonnes nommées dans l’élément column-list. Une nouvelle entrée est créée dans la table pour chaque ligne du résultat de l’instruction SELECT. L’instruction SELECT peut être simple ou composée. Pour consulter la définition des instructions SELECT autorisées, voir SELECT. Le paramètre conflict-algorithm facultatif permet de spécifier un autre algorithme de résolution de conflits de contraintes à utiliser pendant l’exécution de cette commande. Pour une explication et une définition des algorithmes de conflit, voir « Instructions et clauses spéciales » à la page 1166. Les deux formes REPLACE INTO de l’instruction reviennent à utiliser la forme INSERT standard [OR conflictalgorithm] avec l’algorithme de conflit REPLACE (c’est-à-dire la forme INSERT OR REPLACE...). Les deux formes REPLACE INTO de l’instruction reviennent à utiliser la forme INSERT standard [OR conflictalgorithm] avec l’algorithme de conflit REPLACE (c’est-à-dire la forme INSERT OR REPLACE...). UPDATE La commande de mise à jour modifie les enregistrements existants d’un tableau. sql-statement [WHERE expr]
DELETE La commande delete permet de supprimer des enregistrements dans une table. sql-statement
Les instructions de définition des données permettent de créer, de modifier et de supprimer des objets de base de données, tels que des tables, des vues, des index et des déclencheurs. Les instructions de définition de données suivantes sont prises en charge :
• CREATE TABLE Dernière mise à jour le 27/4/2013
Une contrainte CHECK définit une expression qui est évaluée et doit être vraie pour que les données d’une ligne soient insérées ou mises à jour. L’expression CHECK doit donner une valeur booléenne. Une clause COLLATE dans une définition de colonne spécifie la fonction de classement à utiliser pour comparer les entrées texte de la colonne. La fonction de classement BINARY est utilisée par défaut. Pour plus d’informations sur la clause COLLATE et les fonctions de classement, voir COLLATE. Les contraintes DEFAULT spécifient la valeur par défaut à utiliser avec une instruction INSERT. La valeur peut être NULL, une constante de chaîne ou un nombre. La valeur par défaut peut également être l’un des mots-clés spéciaux indépendants de la casse CURRENT_TIME, CURRENT_DATE ou CURRENT_TIMESTAMP. Si la valeur est NULL, une constante de chaîne ou un nombre, elle est insérée littéralement dans la colonne à chaque fois qu’une instruction INSERT ne spécifie pas de valeur pour cette colonne. Si la valeur est CURRENT_TIME, CURRENT_DATE ou CURRENT_TIMESTAMP, la date UTC et/ou l’heure est insérée dans la colonne. CURRENT_TIME gère le format HH:MM:SS. CURRENT_DATE gère le format AAAA-MM-JJ. CURRENT_TIMESTAMP gère le format AAAA-MMJJ HH:MM:SS. La définition d’une contrainte PRIMARY KEY crée généralement un index UNIQUE sur les colonnes correspondantes. Toutefois, si la contrainte PRIMARY KEY s’applique à une seule colonne dont le type de données est INTEGER (ou l’un de ses synonymes, tels qu’int), cette colonne est alors utilisée par la base de données en tant que clé primaire réelle de la table. En d’autres termes, la colonne ne doit contenir que des valeurs entières uniques. (Notez que dans de nombreuses implémentations de SQLite, seul le type de colonne INTEGER entraîne l’utilisation de la colonne en tant que clé primaire interne. Néanmoins, dans Adobe AIR, les synonymes d’INTEGER, tels que int, spécifient également ce comportement.) Si une table ne possède pas de colonne INTEGER PRIMARY KEY, une clé de type entier est automatiquement générée à chaque fois qu’une ligne est insérée. L’accès à la clé primaire d’une ligne s’effectue toujours par l’un des noms spéciaux ROWID, OID ou _ROWID_. Ces noms peuvent être utilisés qu’il s’agisse d’une valeur INTEGER PRIMARY KEY déclarée de façon explicite ou d’une valeur générée en interne. Toutefois, si la table contient une valeur INTEGER PRIMARY KEY explicite, le nom de la colonne dans les données de résultat correspond au nom de la colonne en tant que tel et non au nom spécial. Une colonne INTEGER PRIMARY KEY peut également inclure le mot-clé AUTOINCREMENT. Si le mot-clé AUTOINCREMENT est utilisé, la base de données génère et insère automatiquement une clé de type entier incrémentée séquentiellement dans la colonne INTEGER PRIMARY KEY lorsqu’elle exécute une instruction INSERT qui ne spécifie aucune valeur explicite pour la colonne. Une instruction CREATE TABLE ne peut comporter qu’une seule contrainte PRIMARY KEY. Elle peut faire partie de la définition d’une colonne ou d’une contrainte PRIMARY KEY unique au niveau de la table. Une colonne de clé primaire possède implicitement la valeur NOT NULL. Le paramètre conflict-clause facultatif qui suit plusieurs contraintes permet de spécifier un autre algorithme de résolution de conflits de contraintes par défaut pour cette contrainte. La valeur par défaut est ABORT. Les différentes contraintes d’une même table peuvent gérer différents algorithmes de résolution de conflits par défaut. Si une instruction INSERT ou UPDATE spécifie un autre algorithme de résolution de conflits, celui-ci est utilisé à la place de l’algorithme spécifié dans l’instruction CREATE TABLE. Pour plus d’informations, voir la section ON CONFLICT sous « Instructions et clauses spéciales » à la page 1166.
Si le mot-clé TEMP ou TEMPORARY figure entre CREATE et TABLE, la table créée n’est alors visible que dans le cadre de la même connexion à la base de données (occurrence de SQLConnection). Elle est automatiquement supprimée lors de la fermeture de la connexion à la base de données. Tous les index associés à une table temporaire sont également temporaires. Les tables et index temporaires sont stockés dans un fichier distinct du fichier de base de données principal. Si le préfixe database-name facultatif est spécifié, la table est alors créée dans une base de données nommée (la base de données connectée à l’occurrence de SQLConnection en appelant la méthode attach() avec le nom de base de données spécifié). Spécifier à la fois un préfixe database-name et le mot-clé TEMP est une erreur, sauf si le préfixe databasename est temp. Lorsqu’aucun nom de base de données n’est spécifié et que le mot-clé TEMP n’est pas présent, la table est créée dans la base de données principale (la base de données connectée à l’occurrence de SQLConnection par la méthode open() ou openAsync()). Le nombre de colonnes ou de contraintes présentes dans une table n’est sujet à aucune limite arbitraire. Le volume de données présent dans une ligne n’est pas non plus limité. La forme CREATE TABLE AS définit la table en tant que jeu de résultats d’une requête. Les noms des colonnes de la table sont identiques à ceux des colonnes de résultat. Si la clause IF NOT EXISTS facultative est présente et qu’une autre table porte déjà le même nom, la base de données ignore alors la commande CREATE TABLE. L’instruction DROP TABLE permet de supprimer une table et l’instruction ALTER TABLE d’apporter des modifications limitées. ALTER TABLE La commande ALTER TABLE permet à l’utilisateur de renommer une table existante ou de lui ajouter une nouvelle colonne. Il est impossible de supprimer une colonne dans une table. sql-statement ::= ALTER TABLE [database-name.] table-name alteration alteration ::= RENAME TO new-table-name alteration ::= ADD [COLUMN] column-def
Si la table renommée contient des déclencheurs ou des index, ils demeurent joints à la table après son changement de nom. Toutefois, si des définitions de vue ou des instructions sont exécutées par des déclencheurs faisant référence à la table renommée, elles ne sont pas modifiées automatiquement de sorte à utiliser le nouveau nom de la table. Si une table renommée est associée à des vues ou des déclencheurs, vous devez supprimer et recréer manuellement les déclencheurs ou les définitions de vue en utilisant le nouveau nom de la table. La syntaxe ADD [COLUMN] permet d’ajouter une colonne à une table existante. La nouvelle colonne est toujours ajoutée à la fin de la liste de colonnes existantes. La clause column-def peut prendre toutes les formes autorisées dans une instruction CREATE TABLE, mais est sujette aux restrictions suivantes :
• La colonne ne doit pas posséder la valeur par défaut CURRENT_TIME, CURRENT_DATE ou CURRENT_TIMESTAMP.
La durée d’exécution de l’instruction ALTER TABLE n’est pas affectée par la quantité de données que contient la table. DROP TABLE L’instruction DROP TABLE supprime une table ajoutée à l’aide de l’instruction CREATE TABLE. C’est la table contenant le paramètre table-name spécifié qui est supprimée. Elle disparaît totalement de la base de donnée et du fichier sur disque. Il est impossible de restaurer la table. Tous les index associés à la table sont également supprimés. sql-statement
Le nombre d’index pouvant être associés à une même table n’est sujet à aucune restriction arbitraire. Le nombre de colonnes d’un index n’est pas non plus restreint. DROP INDEX L’instruction DROP INDEX supprime un index ajouté à l’aide de l’instruction CREATE INDEX. L’index spécifié est totalement supprimé du fichier de base de données. L’unique façon de restaurer l’index consiste à entrer à nouveau la commande CREATE INDEX appropriée. sql-statement ::= DROP INDEX [IF EXISTS] [database-name.] index-name
CREATE VIEW La commande CREATE VIEW affecte un nom à une instruction SELECT prédéfinie. Ce nouveau nom peut ensuite être utilisé dans une clause FROM d’une autre instruction SELECT au lieu d’un nom de table. Les vues permettent généralement de simplifier les requêtes en combinant un ensemble de données complexe (et fréquemment utilisé) en une structure exploitable dans d’autres opérations.
Si un élément [database-name] est spécifié, la table est créée dans la base de données nommée (une base de données connectée à l’occurrence de SQLConnection en appelant la méthode attach() avec l’argument name spécifié). Spécifier à la fois un élément [database-name] et le mot-clé TEMP est une erreur, sauf si [database-name] correspond à temp. Lorsqu’aucun nom de base de données n’est spécifié et que le mot-clé TEMP n’est pas présent, la vue est créée dans la base de données principale (la base de données connectée à l’occurrence de SQLConnection avec la méthode open() ou openAsync()). Les vues sont disponibles en lecture seule. Il est impossible d’utiliser une instruction DELETE, INSERT ou UPDATE sur une vue, sauf si un déclencheur au moins du type associé (INSTEAD OF DELETE, INSTEAD OF INSERT, INSTEAD OF UPDATE) est défini. Pour plus d’informations sur la création d’un déclencheur associé à une vue, voir CREATE TRIGGER. Pour supprimer une vue d’une base de données, utilisez l’instruction DROP VIEW. DROP VIEW L’instruction DROP VIEW supprime une vue créée par une instruction CREATE VIEW. sql-statement ::= DROP VIEW [IF EXISTS] view-name
CREATE TRIGGER L’instruction CREATE TRIGGER permet d’ajouter des déclencheurs au schéma de la base de données. Un déclencheur est une opération de base de données (trigger-action) exécutée automatiquement lorsqu’un événement de base de données spécifié (database-event) se produit.
Avec un déclencheur FOR EACH ROW, les instructions trigger-step sont exécutées pour chaque ligne de base de données insérée, mise à jour ou supprimée par l’instruction qui entraîne l’exécution du déclencheur, si l’expression de la clause WHEN est true. Si une clause WHEN est stipulée, les instructions SQL spécifiées en tant « qu’étapes du déclencheur » ne sont exécutées que pour les lignes pour lesquelles la clause WHEN est true. Si aucune clause WHEN n’est stipulée, les instructions SQL sont exécutées pour toutes les lignes. Dans le corps d’un déclencheur (clause trigger-action), les valeurs de la table affectée avant et après la modification sont disponibles à l’aide des noms de table spéciaux OLD et NEW. La structure des tables OLD et NEW correspond à la structure de la table sur laquelle est créé le déclencheur. La table OLD contient les lignes modifiées ou supprimées par l’instruction de déclenchement, dans l’état qui précède les opérations de cette dernière. La table NEW contient les lignes modifiées ou supprimées par l’instruction de déclenchement, dans l’état qui suit les opérations de cette dernière. La clause WHEN et les instructions trigger-step peuvent accéder aux valeurs des lignes insérées, supprimées ou mises à jour à l’aide de références exprimées sous la forme NEW.column-name et OLD.column-name, où column-name est le nom d’une colonne de la table à laquelle est associé le déclencheur. La disponibilité des références de table OLD et NEW varie selon le type d’événement de base de données géré par le déclencheur :
• UPDATE : les références NEW et OLD sont valides. • DELETE : les références OLD sont valides. Toutefois, si une clause ON CONFLICT est spécifiée dans le cadre de l’instruction responsable de l’exécution du déclencheur, la règle de gestion des conflits correspondante est alors utilisée. Outre les déclencheurs de table, un déclencheur INSTEAD OF peut être associé à une vue. Si un ou plusieurs déclencheurs INSTEAD OF INSERT, INSTEAD OF DELETE ou INSTEAD OF UPDATE sont définis sur une vue, l’exécution du type associé d’instruction (INSERT, DELETE ou UPDATE) sur la vue est considérée comme correcte. Dans ce cas, l’exécution d’une instruction INSERT, DELETE ou UPDATE sur la vue entraîne l’activation des déclencheurs associés. Etant donné qu’il s’agit d’un déclencheur INSTEAD OF, les tables sous-jacentes de la vue ne sont pas modifiées par l’instruction qui entraîne l’activation du déclencheur. Les déclencheurs permettent cependant d’exécuter des opérations de modification sur les tables sous-jacentes. Lors de la création d’un déclencheur sur une table contenant une colonne INTEGER PRIMARY KEY, il est important de ne pas oublier l’élément suivant. Si un déclencheur BEFORE modifie la colonne INTEGER PRIMARY KEY d’une ligne qui doit être mise à jour par l’instruction responsable de l’activation du déclencheur, la mise à jour ne se produit pas. La solution consiste à créer la table avec une colonne PRIMARY KEY au lieu d’une colonne INTEGER PRIMARY KEY. L’instruction DROP TRIGGER permet de supprimer un déclencheur. Lors de la suppression d’une table ou d’une vue, tous les déclencheurs associés à la table ou à la vue sont automatiquement supprimés. Fonction RAISE () Une fonction SQL spéciale RAISE() peut être utilisée dans une instruction trigger-step de déclencheur. La syntaxe de cette fonction est la suivante : raise-function
Lors de l’appel de la fonction RAISE(IGNORE), la suite du déclencheur en cours, ainsi que l’instruction responsable de son activation et les déclencheurs éventuellement exécutés par la suite sont abandonnés. Les modifications apportées à la base de données ne sont pas annulées. Si l’instruction responsable de l’exécution du déclencheur fait ellemême partie d’un déclencheur, ce programme est réactivé au début de l’étape suivante. Pour plus d’informations sur les algorithmes de résolution de conflit, voir la section ON CONFLICT (algorithmes de conflit). DROP TRIGGER L’instruction DROP TRIGGER supprime un déclencheur créé par l’instruction CREATE TRIGGER. sql-statement
éléments de langage utilisables dans de nombreux commentaires, instructions et expressions. COLLATE La clause COLLATE est utilisée dans les instructions SELECT, CREATE TABLE et CREATE INDEX pour définir l’algorithme de comparaison qui permet de comparer et trier des valeurs. sql-statement collation-name
::= Aucune séquence de classement n’est utilisée pour les classes de stockage de type NULL, BLOB, INTEGER ou REAL. Pour utiliser un type de classement autre que BINARY avec une colonne, une clause COLLATE doit être spécifiée dans le cadre de la définition de la colonne dans l’instruction CREATE TABLE. Chaque fois que deux valeurs TEXT sont comparées, une séquence de classement permet de déterminer les résultats de la comparaison, selon les règles suivantes :
BETWEEN...AND suit la règle précédente pour identifier la séquence de classement.
Si tel n’est pas le cas, lorsque l’expression triée par une clause ORDER BY est une colonne, le type de classement par défaut de cette colonne est utilisé pour déterminer l’ordre de tri. Si l’expression n’est pas une colonne, la séquence de classement BINARY est utilisée. EXPLAIN Le modificateur de commande EXPLAIN est une extension non standard de SQL. sql-statement
ON CONFLICT (algorithmes de conflit) La clause ON CONFLICT n’est pas une commande SQL distincte, mais une clause non standard susceptible de figurer dans un grand nombre d’autres commandes SQL. conflict-clause conflict-clause conflict-algorithm
::= ROLLBACK Lorsqu’une violation de contrainte se produit, ROLLBACK survient immédiatement et met fin à la
ABORT Lorsqu’une violation de contrainte se produit, la commande retire toute modification précédente
ROLLBACK n’étant exécuté, les modifications apportées par les commandes précédentes dans une transaction sont donc conservées. ABORT correspond au comportement par défaut. FAIL Lorsqu’une violation de contrainte se produit, la commande est annulée et l’occurrence de SQLStatement
à jour, les modifications apportées aux 99 premières lignes sont conservées, mais la ligne 100 et les suivantes ne sont pas modifiées. IGNORE Lorsqu’une violation de contrainte se produit, la ligne concernée n’est ni insérée, ni modifiée. Mise à part la
REPLACE Lorsqu’une violation de contrainte UNIQUE se produit, les lignes préexistantes à l’origine de cette violation sont supprimées avant l’insertion ou la mise à jour de la ligne en cours. Par conséquent, l’insertion ou la mise à jour se produit toujours, et l’exécution de la commande se poursuit normalement. Aucune erreur n’est renvoyée. Si une violation de contrainte NOT NULL se produit, la valeur NULL est remplacée par la valeur par défaut de la colonne. Si la colonne n’a pas de valeur par défaut, l’algorithme ABORT est utilisé. Si une violation de contrainte CHECK se produit, l’algorithme IGNORE est utilisé. Lorsque cette stratégie de résolution de conflits supprime des lignes pour respecter une contrainte, elle n’invoque pas de déclencheurs de suppression sur ces lignes.
EXPRESSIONS Les expressions sont des sous-commandes placées dans d’autres blocs SQL. La syntaxe valide d’une expression placée dans une instruction SQL est la suivante :
Un littéral BLOB est un littéral de chaîne contenant des données hexadécimales et précédé d’un seul caractère x ou X, tel que X'53514697465'. Une valeur littérale peut également être le jeton NULL. Nom de colonne Un nom de colonne peut être tout nom défini dans l’instruction CREATE TABLE ou l’un des identifiants spéciaux suivants : ROWID, OID ou _ROWID_. Ces identifiants spéciaux décrivent tous la clé aléatoire unique de type entier (« clé de la ligne »), associée à chaque ligne de chaque table. Les identifiants spéciaux ne font référence à la clé de la ligne que si l’instruction CREATE TABLE ne définit pas de colonne réelle portant le même nom. Les clés des lignes se comportent comme des colonnes en lecture seule. Une clé de ligne peut se substituer à toute colonne ordinaire, mais vous ne pouvez pas en modifier la valeur dans une instruction UPDATE ou INSERT. Le jeu de résultats de l’instruction de table SELECT * FROM ne comprend pas de clé de ligne. Instruction SELECT Une instruction SELECT peut apparaître dans une expression comme opérande de droite de l’opérateur IN, comme quantité scalaire (valeur de résultat unique) ou comme opérande d’un opérateur EXISTS. Lorsqu’elle est utilisée en tant que quantité scalaire ou qu’opérande d’un opérateur IN, le résultat de l’instruction SELECT ne peut contenir qu’une seule colonne. Une instruction SELECT composée (connectée par des mots-clés tels qu’UNION ou EXCEPT) est autorisée. Avec l’opérateur EXISTS, les colonnes du jeu de résultats de SELECT sont ignorées et l’expression renvoie TRUE si le jeu de résultats contient une ou plusieurs lignes, FALSE s’il est vide. Lorsqu’aucun terme de l’expression SELECT ne fait référence à la valeur de la requête conteneur, l’expression est évaluée une fois avant tout autre traitement et le résultat est réutilisé selon les besoins. Si l’expression SELECT contient des variables issues de la requête externe, appelée sous-requête corrélée, l’instruction SELECT est réévaluée à chaque fois que cela est nécessaire. Lorsqu’une expression SELECT est l’opérande de droite de l’opérateur IN, l’opérateur IN renvoie TRUE si le résultat de l’opérande de gauche est égal à l’une des valeurs du jeu de résultats de l’instruction SELECT. L’opérateur IN peut être précédé du mot-clé NOT pour inverser le sens du test. Lorsqu’une instruction SELECT apparaît dans une expression, mais n’est pas l’opérande droit d’un opérateur IN, la première ligne du résultat de SELECT devient la valeur utilisée dans l’expression. Si l’instruction SELECT produit plusieurs lignes de résultat, seule la première ligne est prise en compte. Si l’instruction SELECT ne produit pas de ligne de résultats, sa valeur est NULL. Expression CAST Une expression CAST remplace le type de données de la valeur spécifiée par le type donné. Le type spécifié peut être tout nom de type non vide géré par le type dans la définition de colonne d’une instruction CREATE TABLE. Pour plus d’informations, voir Prise en charge des types de données.
Comme tous les mots-clés dans SQL, les noms de fonction ne respectent pas la casse. Fonctions d’agrégation Les fonctions d’agrégation exécutent des opérations sur des valeurs issues de plusieurs lignes. Elles sont principalement utilisées dans des instructions SELECT en conjonction avec la clause GROUP BY. AVG(X)
Renvoie la valeur minimale non NULL de toutes les valeurs du groupe. Pour déterminer cette valeur minimale, l’ordre de tri standard est utilisé. Si toutes les valeurs du groupe sont NULL, NULL est renvoyé. Renvoie la somme numérique de toutes les valeurs non NULL du groupe. Si toutes les valeurs sont NULL, SUM() renvoie NULL et TOTAL() renvoie 0.0. Le résultat de TOTAL() est toujours une valeur à virgule flottante. SUM() a pour résultat une valeur entière si toutes les entrées non NULL sont des nombres entiers. Si l’une des entrées de SUM() n’est pas un nombre entier et n’est pas NULL, SUM() renvoie une valeur à virgule flottante. Cette valeur peut être une approximation de la somme réelle.
DISTINCT. Dans ce cas, les éléments en double sont filtrés avant d’être transmis à la fonction d’agrégation. Par exemple, l’appel de la fonction COUNT(DISTINCT x) renvoie le nombre de valeurs distinctes de la colonne X au lieu du nombre total de valeurs non NULL que contient la colonne x. Fonctions scalaires Les fonctions scalaires opèrent sur les valeurs d’une ligne à la fois. ABS(X) COALESCE(X, Y, ...) Dernière mise à jour le 27/4/2013
Renvoie l’identifiant de ligne (clé primaire générée) de la dernière ligne insérée dans la base de données via l’occurrence de SQLConnection en cours. Cette valeur est identique à la valeur renvoyée par la propriété SQLConnection.lastInsertRowID. Renvoie la longueur de la chaîne de X en caractères. Cette fonction permet de mettre en œuvre la syntaxe X LIKE Y [ESCAPE Z] de SQL. Si la clause ESCAPE facultative est présente, la fonction est appelée avec trois arguments. Dans le cas contraire, elle est appelée avec deux arguments seulement. Renvoie une copie de la chaîne X dont tous les caractères sont convertis en minuscules. Renvoie une chaîne qui résulte de la suppression des espaces du côté gauche de X. Si un argument Y est spécifié, la fonction supprime tous les caractères de Y du côté gauche de X. Renvoie l’argument possédant la valeur maximale. Outre les nombres, les arguments peuvent être des chaînes. La valeur maximale est déterminée par l’ordre de tri défini. Notez que MAX() est une fonction simple lorsqu’elle possède plusieurs arguments, mais une fonction d’agrégation lorsqu’elle n’en a qu’un seul. Renvoie l’argument possédant la valeur minimale. Outre les nombres, les arguments peuvent être des chaînes. La valeur minimale est déterminée par l’ordre de tri défini. Notez que MIN() est une fonction simple lorsqu’elle possède plusieurs arguments, mais une fonction d’agrégation lorsqu’elle n’en a qu’un seul. Renvoie le premier argument si les arguments diffèrent, sinon elle renvoie NULL. Cette routine renvoie une chaîne correspondant à la valeur de l’argument pouvant être inclus dans une autre instruction SQL. Les chaînes sont entourées de guillemets simples avec caractères d’échappement sur les guillemets intérieurs si nécessaire. Les classes de stockage BLOB sont codées comme des littéraux hexadécimaux. La fonction s’avère utile lors de l’écriture de déclencheurs pour implémenter la fonctionnalité d’annulation et de rétablissement. Renvoie un nombre entier pseudo-aléatoire compris entre -9223372036854775808 et 9223372036854775807. Cette valeur aléatoire n’est pas chiffrée en dur. Renvoie un BLOB N-octets contenant des octets pseudo-aléatoires. N doit être un nombre entier positif. Cette valeur aléatoire n’est pas chiffrée en dur. Si la valeur de N est négative, un octet unique est renvoyé. Arrondit le nombre X à Y chiffres après la virgule. Si l’argument Y est omis, 0 est utilisé. Renvoie une chaîne qui résulte de la suppression des espaces du côté droit de X. Si un argument Y est spécifié, la fonction supprime tous les caractères de Y du côté droit de X. Renvoie une sous-chaîne de la chaîne d’entrée X commençant par le Yième caractère et longue de Z caractères. Le caractère le plus à gauche de X est la position d’index 1. Si Y est négatif, le premier caractère de la sous-chaîne est détecté en comptant à partir de la droite et non à partir de la gauche. Renvoie une chaîne qui résulte de la suppression des espaces du côté droit de X. Si un argument Y est spécifié, la fonction supprime tous les caractères de Y du côté droit de X. Renvoie le type de l’expression X. Les valeurs gérées sont « null », « integer », « real », « text » et « blob ». Pour plus d’informations sur les types de données, voir Prise en charge des types de données. Renvoie une copie de la chaîne d’entrée X convertie en majuscules. Renvoie un BLOB contenant N octets de 0x00.
Les fonctions de formatage de la date et de l’heure sont un groupe de fonctions scalaires qui permettent de créer des données de date et d’heure formatées. Notez que ces fonctions traitent et renvoient des valeurs de chaîne et des valeurs numériques. Elles ne sont pas conçues pour être utilisées avec le type de données DATE. Si vous utilisez ces fonctions sur les données d’une colonne dont le type de données déclaré est DATE, leur comportement est imprévisible. DATE(T, ...)
La routine STRFTIME() renvoie la date formatée selon la chaîne de format spécifiée en tant que premier argument F. La chaîne de format prend en charge les substitutions suivantes : %d : jour du mois %f : secondes fractionnaires (SS.SSS) %H : heure (00-24) %j : jour de l’année (001-366) %J : nombre de jours Julien Date et heure en cours exprimées au format UCT (Universal Coordinated Time) Nombre de jours Julien exprimé sous forme de nombre à virgule flottante.
Nombre de minutes à ajouter à l’heure. Nombre de secondes et de millisecondes à ajouter à l’heure. Nombre de mois à ajouter à l’heure. Nombre d’années à ajouter à l’heure. Ramène l’heure au début du mois. Ramène l’heure au début de l’année. Ramène l’heure au début de la journée. Fait avancer l’heure jusqu’au jour de la semaine spécifié. (0 = dimanche, 1 = lundi, etc.). Convertit la date au format local. Convertit la date au format UCT (Universal Coordinated Time).
SQL prend en charge un grand nombre d’opérateurs, dont les opérateurs courants qui existent dans la plupart des langages de programmation, ainsi que plusieurs opérateurs propres à SQL. Opérateurs courants Les opérateurs binaires suivants sont autorisés dans un bloc SQL et sont recensés par ordre de priorité décroissant : * / L’opérateur || est l’opérateur de concaténation de chaînes. Il relie les deux chaînes de ses opérandes. L’opérateur % a pour résultat le reste de son opérande de gauche modulo son opérande de droite. Le résultat de tout opérateur binaire est une valeur numérique, à l’exception de l’opérateur de concaténation ||, dont le résultat est une chaîne. Opérateurs SQL LIKE L’opérateur LIKE effectue une comparaison de correspondance basée sur un modèle. expr pattern
::= L’opérande de droite de l’opérateur LIKE contient le modèle, tandis que l’opérande de gauche contient la chaîne à comparer au modèle. Un symbole de pourcentage (%) dans le modèle représente un caractère générique. Il correspond à toute séquence de zéro, un ou plusieurs caractères de la chaîne. Un caractère de soulignement (_) dans le modèle correspond à tout caractère unique de la chaîne. Tous les autres caractères correspondent à leur valeur ou à leur équivalent majuscule/minuscule. En d’autres termes, la correspondance ne respecte pas la casse. (Remarque : le moteur de base de données gère la casse des caractères latins 7 bits uniquement. Par conséquent, l’opérateur LIKE respecte la casse des caractères UTF-8 ou iso8859 8 bits. Ainsi, l’expression 'a' LIKE 'A' est TRUE, mais 'æ' LIKE 'Æ' est FALSE). La propriété SQLConnection.caseSensitiveLike permet de modifier le respect de la casse pour les caractères latins. Si la clause facultative ESCAPE est présente, l’expression qui suit le mot-clé ESCAPE doit correspondre à une chaîne composée d’un seul caractère. Ce caractère peut être utilisé dans le modèle LIKE pour correspondre aux caractères littéraux de pourcentage ou de soulignement. Le caractère échappement suivi du symbole de pourcentage, d’un soulignement ou de lui-même correspond respectivement à un symbole de pourcentage, à un soulignement ou à un caractère d’échappement littéral dans la chaîne. GLOB L’opérateur GLOB est similaire à LIKE, mais utilise la syntaxe globbing de fichier Unix pour ses caractères génériques. A l’encontre de LIKE, GLOB respecte la casse. IN L’opérateur IN calcule si son opérande de gauche est égal à l’une des valeurs de son opérande de droite (ensemble de valeurs entre parenthèses). in-expr
NOT pour inverser le sens du test (en d’autres termes, pour vérifier qu’une valeur ne correspond pas au modèle indiqué).
Un paramètre spécifie dans l’expression un espace réservé associé à une valeur littérale renseignée au moment de l’exécution en affectant une valeur au tableau associatif SQLStatement.parameters. Les paramètres gèrent trois formes : ? Contraintes FOREIGN KEY Les contraintes FOREIGN KEY sont analysées, mais ne sont pas imposées. Déclencheurs Les déclencheurs FOR EACH STATEMENT ne sont pas pris en charge (tous les déclencheurs doivent
ALTER TABLE Seules les variantes RENAME TABLE et ADD COLUMN de la commande ALTER TABLE sont prises en charge. Les autres types d’opérations ALTER TABLE, tels que DROP COLUMN, ALTER COLUMN, ADD CONSTRAINT, etc. sont ignorés. Transactions imbriquées Une seule transaction active est autorisée. RIGHT OUTER JOIN et FULL OUTER JOIN RIGHT OUTER JOIN et FULL OUTER JOIN ne sont pas pris en charge. VIEW actualisable Une vue est disponible en lecture seule. Il est impossible d’exécuter une instruction DELETE,
INSERT ou UPDATE sur une vue est pris en charge et permet de mettre à jour les tables de soutien dans le corps du déclencheur. GRANT et REVOKE Une base de données est un fichier de disque ordinaire ; les seules autorisations d’accès à appliquer sont les autorisations d’accès au fichier standard du système d’exploitation sous-jacent. Les commandes GRANT et REVOKE fréquemment détectées sur les systèmes SGBDR client/serveur ne sont pas implémentées.
SQLConnection : Eléments SQL liés aux transactions (BEGIN, END, COMMIT, ROLLBACK) Cette fonctionnalité est disponible par le biais des méthodes liées aux transactions de la classe SQLConnection, SQLConnection.begin(), SQLConnection.commit() et SQLConnection.rollback(). ANALYZE Cette fonctionnalité est disponible par le biais de la méthode SQLConnection.analyze(). ATTACH Cette fonctionnalité est disponible par le biais de la méthode SQLConnection.attach(). COPY Cette instruction n’est pas prise en charge. CREATE VIRTUAL TABLE Cette instruction n’est pas prise en charge. DETACH Cette fonctionnalité est disponible par le biais de la méthode SQLConnection.detach(). PRAGMA Cette instruction n’est pas prise en charge. VACUUM Cette fonctionnalité est disponible par le biais de la méthode SQLConnection.compact(). L’accès aux tables système n’est pas disponible. Les tables système, y compris sqlite_master et d’autres tables dotées du préfixe « sqlite_ » ne sont pas disponibles dans les instructions SQL. Le moteur d’exécution comprend une API de schéma qui permet d’accéder aux données du schéma par le biais d’une solution orientée objets. Pour plus d’informations, voir la méthode SQLConnection.loadSchema(). Fonctions d’expression régulière (MATCH() et REGEX()) Ces fonctions ne sont pas disponibles dans les instructions SQL.
Paramètres d’instruction indexés Dans de nombreuses implémentations, les paramètres d’instruction indexés sont
Définitions de colonne INTEGER PRIMARY KEY Dans de nombreuses implémentations, seules les colonnes définies
(notez qu’à l’instar de tous les mots-clés dans SQL, ces noms de types de données ne respectent pas la casse) : Boolean correspond à la classe Boolean. Date correspond à la classe Date. int correspond à la classe int (équivaut à l’affinité de colonne INTEGER). Number correspond à la classe Number (équivaut à l’affinité de colonne REAL). Object correspond à la classe Object ou à toute sous-classe pouvant être sérialisée ou désérialisée par le biais d’AMF3.
String correspond à la classe String (équivaut à l’affinité de colonne TEXT). XML correspond à la classe XML d’ActionScript (E4X). XMLList correspond à la classe XMLList d’ActionScript (E4X).
Contrairement à la plupart des bases de données SQL, le moteur de la base de données SQL d’Adobe AIR ne requiert pas ou n’impose pas que les colonnes des tables contiennent des valeurs d’un type donné. Le moteur d’exécution utilise plutôt deux concepts, les classes de stockage et l’affinité de colonne, pour contrôler les types de données. Cette section décrit les classes de stockage et l’affinité de colonne, ainsi que la résolution des différences de types de données selon les cas :
• « Affinité de colonne » à la page 1178 • « Types de données et opérateurs de comparaison » à la page 1181 • « Types de données et opérateurs mathématiques » à la page 1181
• « Types de données et regroupement » à la page 1182 • « Types de données et instructions SELECT composées » à la page 1182
Les classes de stockage représentent les types de données réels utilisés pour stocker des valeurs dans une base de données. La base de données fait appel aux classes de stockage suivantes : NULL La valeur est une valeur NULL. INTEGER La valeur est un nombre entier signé. REAL La valeur est une valeur à virgule flottante. TEXT La valeur est une chaîne texte (de 256 Mo au plus). BLOB La valeur est un BLOB (Binary Large Object), c’est-à-dire des données binaires brutes (de 256 Mo au plus).
Les valeurs littérales qui font partie d’une instruction SQL se voient affecter la classe de stockage TEXT si elles sont placées entre guillemets simples ou doubles, INTEGER si la valeur littérale est un nombre sans guillemet et sans décimale ou exposant, REAL si la valeur littérale est un nombre sans guillemet avec décimale ou exposant et NULL si la valeur est NULL. Les valeurs littérales avec classe de stockage BLOB sont spécifiées par la notation X'ABCD’. Pour plus d’informations, voir la section consacrée aux valeurs littérales dans les expressions. Les valeurs fournies en tant que paramètres via le tableau associatif SQLStatement.parameters se voient affecter la classe de stockage la plus proche de la liaison native du type de données. Par exemple, les valeurs int sont liées en tant que classe de stockage INTEGER, les valeurs Number obtiennent la classe de stockage REAL, les valeurs String obtiennent la classe de stockage TEXT et les objets ByteArray obtiennent la classe de stockage BLOB.
L’affinité d’une colonne correspond au type recommandé des données stockées dans cette colonne. Lorsqu’une valeur est stockée dans une colonne (par une instruction INSERT ou UPDATE), le moteur d’exécution tente de convertir le type de données de cette valeur en l’affinité spécifiée. Par exemple, si une valeur Date (occurrence de Date ActionScript ou JavaScript) est insérée dans une colonne dont l’affinité est TEXT, elle est convertie en représentation String (ce qui équivaut à appeler la méthode toString() de l’objet) avant d’être stockée dans la base de données. Si la valeur ne peut pas être convertie en l’affinité spécifiée, une erreur est renvoyée et l’opération n’est pas exécutée. Lorsqu’une valeur est récupérée dans la base de données par une instruction SELECT, elle est renvoyée sous forme d’occurrence de la classe correspondant à l’affinité, qu’elle ait été ou non convertie à partir d’un autre type de données lors de son stockage. Si une colonne accepte les valeurs NULL, la valeur null ActionScript ou JavaScript peut servir de valeur de paramètre pour stocker NULL dans la colonne. Lorsqu’une valeur de classe de stockage NULL est récupérée dans une instruction SELECT, elle est toujours renvoyée en tant que valeur null ActionScript ou JavaScript, quelle que soit l’affinité de la colonne. Lorsqu’une colonne accepte les valeurs NULL, vérifiez toujours les valeurs récupérées dans cette colonne pour déterminer si elles sont null avant de tenter d’attribuer aux valeurs un type qui ne peut pas être null (Number ou Boolean, par exemple). L’une des affinités de type suivantes est affectée à chaque colonne de la base de données :
Lorsque des données texte sont insérées dans une colonne NUMERIC, le système tente de les convertir en nombres entiers ou réels avant de les stocker. Si la conversion aboutit, la valeur est stockée à l’aide de la classe de stockage INTEGER ou REAL (la valeur « 10,05 » est par exemple convertie en classe de stockage REAL avant d’être stockée). S’il est impossible d’effectuer la conversion, il se produit une erreur. Aucune tentative de conversion d’une valeur NULL est exécutée. Une valeur récupérée dans une colonne NUMERIC est renvoyée sous forme d’occurrence du type numérique le plus spécifique adapté à la valeur. En d’autres termes, si la valeur est un nombre entier positif ou 0, elle est renvoyée sous forme d’occurrence d’uint. S’il s’agit d’un nombre entier négatif, elle est renvoyée sous forme d’occurrence d’int. Enfin, s’il s’agit d’un composant à virgule flottante (et non d’un nombre entier), elle est renvoyée sous forme d’occurrence de Number. INTEGER (ou int) Une colonne qui utilise l’affinité INTEGER se comporte comme une colonne dont l’affinité est NUMERIC, à une exception près. Si la valeur à stocker est une valeur réelle (par exemple une occurrence de Number) sans composant à virgule flottante, ou si la valeur est une valeur de texte pouvant être convertie en valeur réelle sans composant à virgule flottante, elle est convertie en nombre entier et stockée à l’aide de la classe de stockage INTEGER. En cas de tentative de stockage d’une valeur réelle avec un composant à virgule flottante, une erreur se produit. REAL (ou Number) Une colonne dont l’affinité est REAL ou NUMBER se comporte comme une colonne d’affinité NUMERIC, sauf qu’elle convertit les valeurs entières en représentation à virgule flottante. Les valeurs d’une colonne REAL sont toujours renvoyées à partir de la base de données sous forme d’occurrences de Number. Boolean Une colonne d’affinité BOOLEAN stocke des valeurs true ou false. Une colonne BOOLEAN gère une valeur correspondant à une occurrence de Boolean ActionScript ou JavaScript. Si le code tente de stocker une valeur String, une valeur String dont la longueur est supérieure à zéro est considérée comme true, une valeur String vide comme false. Si le code tente de stocker des données numériques, toute valeur autre que zéro est stockée en tant que true et 0 est stocké en tant que false. Lorsqu’une valeur Boolean est récupérée par une instruction SELECT, elle est renvoyée en tant qu’occurrence de Boolean. Les valeurs non NULL sont stockées à l’aide de la classe de stockage INTEGER (0 pour false et 1 pour true) et sont converties en objet Boolean lors de la récupération des données.
Une colonne d’affinité DATE stocke des valeurs de date et d’heure. Une colonne DATE est conçue pour accepter des valeurs qui sont des occurrences de Date ActionScript ou JavaScript. En cas de tentative de stockage d’une valeur String dans une colonne DATE, le moteur d’exécution tente de la convertir en date julienne. Si la conversion échoue, il se produit une erreur. Si le code tente de stocker une valeur Number, int ou uint, il ne se produit pas de tentative de validation des données et il est considéré comme acquis qu’il s’agit d’une valeur de date julienne valide. Une valeur DATE récupérée par une instruction SELECT est automatiquement convertie en occurrence de Date. Les valeurs DATE étant stockées en tant que valeurs de dates juliennes avec la classe de stockage REAL, les opérations de tri et de comparaison fonctionnent comme prévu. XML ou XMLList Une colonne qui utilise une affinité XML ou XMLLIST stocke des structures XML. Lorsque le code tente de stocker des données dans une colonne XML en utilisant un paramètre SQLStatement, le moteur d’exécution tente de convertir et de valider la valeur à l’aide de la fonction ActionScript XML() ou XMLList(). Si la valeur ne peut pas être convertie en code XML valide, une erreur se produit. Si la tentative de stockage des données utilise une valeur de texte SQL littérale (INSERT INTO (col1) VALUES ('Invalid XML (no closing tag)', par exemple), la valeur n’est ni analysée, ni validée, car son format est considéré comme correct. Si une valeur non valide est stockée, elle est renvoyée en tant qu’objet XML vide lorsqu’elle est récupérée. Les données XML et XMLLIST sont stockées à l’aide de la classe de stockage TEXT ou NULL. Object Une colonne d’affinité Object stocke des objets complexes ActionScript ou JavaScript, y compris des occurrences de la classe Object, des occurrences des sous-classes Object telles que les occurrences d’Array, voire des occurrences des classes personnalisées. Les données de la colonne Object sont sérialisées au format AMF3 et stockées avec la classe de stockage BLOB. Lorsqu’une valeur est récupérée, elle est désérialisée du format AMF3 et renvoyée sous forme d’occurrence de leur classe d’origine. Notez que certaines classes ActionScript, en particulier les objets d’affichage, ne peuvent pas être désérialisées en tant qu’occurrences de leur type de données d’origine. Avant de stocker une occurrence de classe personnalisée, vous devez enregistrer un alias pour la classe avec la méthode flash.net.registerClassAlias() (ou dans Flex, en ajoutant des métadonnées [RemoteObject] à la déclaration de la classe). Avant de récupérer les données, vous devez également enregistrer le même alias pour la classe. Toutes les données qui ne peuvent pas être désérialisées correctement, que le problème soit inhérent à la classe ou dû au fait qu’un alias de classe est introuvable ou ne correspond pas à la valeur requise, sont renvoyées sous forme d’objet anonyme (une occurrence de la classe Object) dont les propriétés et les valeurs correspondent à l’occurrence d’origine telle qu’elle a été stockée. NONE Une colonne d’affinité NONE ne privilégie aucune classe de stockage. Elle ne tente pas de convertir les données avant de les insérer. Identification de l’affinité L’affinité de type d’une colonne est déterminée par le type déclaré de la colonne dans l’instruction CREATE TABLE. Lors de la détermination du type, les règles suivantes (non sensibles à la casse) sont appliquées :
• Si le type de données correspond à la chaîne « XML », l’affinité de la colonne est XML. • Si le type de données contient la chaîne « OBJE », l’affinité de la colonne est Object. • Si le type de données contient la chaîne « BOOL », l’affinité de la colonne est Boolean. • Si le type de données contient la chaîne « DATE», l’affinité de la colonne est Date. • Si le type de données contient la chaîne « INT» (y compris « UINT »), l’affinité de la colonne est INTEGER/int. • Si le type de données d’une colonne contient la chaîne « REAL », « NUMB », « FLOA » ou « DOUB », l’affinité de la colonne est REAL/Number.
• Si une table est créée à l’aide d’une instruction CREATE TABLE t AS SELECT..., aucun type de données n’est spécifié pour les colonnes et l’affinité NONE leur est affectée.
Les opérateurs de comparaison binaires suivants, =, <, <=, >= et != sont pris en charge, ainsi qu’une opération permettant de tester l’appartenance, IN, et l’opérateur de comparaison ternaire BETWEEN. Pour plus d’informations sur ces opérateurs, voir Opérateurs. Le résultat d’une comparaison dépend des classes de stockage des deux valeurs comparées. Lors de la comparaison de deux valeurs, les règles suivantes sont appliquées :
REAL est comparée à une autre valeur INTEGER ou REAL, une comparaison numérique est effectuée.
L’opérateur ternaire BETWEEN est toujours remanié en tant qu’expression binaire équivalente. Par exemple, a BETWEEN b AND c est transformé en a >= b AND a <= c, même si cela signifie que des affinités différentes sont appliquées à a dans chacune des comparaisons requises pour évaluer l’expression. Les expressions de type a IN (SELECT b ....) sont gérées selon les trois règles énumérées précédemment pour les comparaisons binaires, c’est-à-dire de la même façon que a = b. Par exemple, si b est une valeur de colonnes et a une expression, l’affinité de b est appliquée à a avant toute comparaison. L’expression a IN (x, y, z) est transformée en a = +x OR a = +y OR a = +z. Les valeurs situées à droite de l’opérateur IN (soit les valeurs x, y et z dans cet exemple) sont considérées comme des expressions, même s’il s’agit de valeurs de colonne. Si la valeur située à gauche de l’opérateur IN est une colonne, l’affinité de cette dernière est utilisée. Si la valeur est une expression, il ne se produit pas de conversion. L’utilisation de la clause COLLATE peut également affecter la manière dont les comparaisons sont effectuées. Pour plus d’informations, voir COLLATE.
Pour chaque opérateur mathématique pris en charge (*, /, %, + et -), l’affinité numérique est appliquée à chaque opérande avant d’évaluer l’expression. S’il est impossible de convertir un opérande en classe de stockage NUMERIC, l’évaluation de l’expression donne le résultat NULL.
Si l’opérateur de concaténation || est utilisé, chaque opérande est converti en classe de stockage TEXT avant que l’expression ne soit évaluée. S’il est impossible de convertir un opérande en classe de stockage TEXT, le résultat de l’expression est NULL. Il peut s’avérer impossible de convertir la valeur dans deux cas de figure : soit la valeur de l’opérande est NULL, soit il s’agit d’un objet BLOB contenant une classe de stockage dont le type est autre que TEXT.
Lorsque les valeurs sont triées par une clause ORDER BY, les valeurs associées à la classe de stockage NULL sont prioritaires. Elles sont suivies des valeurs INTEGER et REAL classées par ordre numérique, suivies des valeurs TEXT classées par ordre binaire ou selon le classement spécifié (BINARY ou NOCASE). Les valeurs BLOB arrivent en dernière position, classées par ordre binaire. Il ne se produit pas de conversion des classes de stockage avant le tri.
Lors d’un regroupement des valeurs à l’aide de la clause GROUP BY, les valeurs associées à des classes de stockage différentes sont considérées comme distinctes. Les valeurs INTEGER et REAL font exception à la règle, car elles sont considérées comme égales si elles sont équivalentes d’un point de vue numérique. Aucune affinité n’est appliquée aux valeurs suite à l’exécution d’une clause GROUP BY.
Les opérateurs SELECT composés (UNION, INTERSECT et EXCEPT) effectuent des comparaisons implicites entre les valeurs. Avant l’exécution de ces comparaisons, une affinité est susceptible d’être appliquée à chaque valeur. La même infinité est appliquée le cas échéant à toutes les valeurs pouvant être renvoyées dans une seule colonne du jeu de résultats SELECT composé. L’affinité appliquée correspond à l’affinité de la colonne renvoyée par la première instruction SELECT de composant dont une valeur de colonne (et non un autre type d’expression) occupe cette position. Si, pour une colonne SELECT composée donnée, aucune instruction SELECT de composant ne renvoie de valeur de colonne, aucune affinité n’est appliquée aux valeurs de cette colonne avant leur comparaison.
Le tableau ci-dessous contient la liste des valeurs detailID et le texte du message d’erreur associé en anglais. Le texte d’espace réservé dans les messages indique l’emplacement où sont substituées les valeurs de detailArguments par le moteur d’exécution. Cette liste peut servir de source de localisation des messages d’erreur susceptibles d’être générés lors d’opérations de bases de données SQL. SQLError detailID 1001 1102 Not a writable directory. (Il est impossible d’écrire dans ce répertoire.) Unknown or unsupported join type: '%s %s %s’ (Type de jointure inconnu ou non pris en charge : '%s %s %s’) RIGHT and FULL OUTER JOINs are not currently supported. (Les jointures RIGHT et FULL OUTER ne sont pas prises en charge actuellement.) A NATURAL join may not have an ON or USING clause. (Il est possible qu’une jointure NATURAL n’ait pas de clause ON ou USING.)
ID, arguments et messages d’erreur SQL détaillés
No such column: %s[.%s[.%s]] (Cette colonne n’existe pas : %s[.%s[.%s]]) VACUUM is not allowed from SQL. (VACUUM n’est pas autorisé depuis une instruction SQL.) Table '%s': indexing function returned an invalid plan. (Table '%s' : une fonction d’indexation a renvoyé un plan non valide.) At most %d tables in a join. (Une jointure ne doit pas comporter plus de %d tables.) Cannot add a PRIMARY KEY column. (Impossible d’ajouter une colonne PRIMARY KEY.) Cannot add a UNIQUE column. (Impossible d’ajouter une colonne UNIQUE.) Cannot add a NOT NULL column with default value NULL. (Impossible d’ajouter une colonne NOT NULL avec la valeur par défaut NULL.) Cannot add a column with non-constant default. (Impossible d’ajouter une colonne avec une valeur par défaut non constante.) Cannot add a column to a view. (Impossible d’ajouter une colonne à une vue.) ANALYZE is not allowed in SQL. (ANALYZE n’est pas autorisé dans SQL.) Invalid name: '%s' (Nom non valide : '%s')
Conflicting ON CONFLICT clauses specified. (Les clauses ON CONFLICT spécifiées sont sources de conflit.) No such index: '%s' (Cet index n’existe pas : '%s') Index associated with UNIQUE or PRIMARY KEY constraint cannot be dropped. (L’index associé à la contrainte UNIQUE ou PRIMARY KEY ne peut pas être abandonné.) BEGIN is not allowed in SQL. (BEGIN n’est pas autorisé dans SQL.) COMMIT is not allowed in SQL. (COMMIT n’est pas autorisé dans SQL.) ROLLBACK is not allowed in SQL. (ROLLBACK n’est pas autorisé dans SQL.) Unable to open a temporary database file for storing temporary tables. (Impossible d’ouvrir un fichier de base de données temporaire pour stocker des tables temporaires.) Unable to identify the object to be reindexed. (Impossible d’identifier l’objet à réindexer.) Table '%s' may not be modified. (Il est interdit de modifier la table '%s'.) Cannot modify '%s' because it is a view. (Impossible de modifier '%s' car il s’agit d’une vue.) Variable number must be between ?0 and ?%d< (Le nombre de variables doit être compris entre ?0 et ?%d<) Misuse of aliased aggregate '%s' (Utilisation incorrecte de l’agrégat crénelé '%s') Ambiguous column name: '[%s.[%s.]]%s’ (Nom de colonne ambigu : '[%s.[%s.]]%s’) No such function: '%s' (Cette fonction n’existe pas : '%s') Wrong number of arguments to function '%s' (Nombre incorrect d’arguments pour la fonction '%s') Subqueries prohibited in CHECK constraints. (Les sous-requêtes sont interdites dans les contraintes CHECK.) Parameters prohibited in CHECK constraints. (Les paramètres sont interdits dans les contraintes CHECK.)
[column|columns] '%s'[,'%s'] are not [unique|is] not unique. (La/les [colonne|colonnes] '%s'[,'%s'] n’est pas [unique|ne sont] pas uniques.) Malformed database schema. (Schéma de base de données incorrectement formé.) Unsupported file format. (Format de fichier non pris en charge.) Unrecognized token: '%s' (Jeton non reconnu : '%s') Could not convert text value to numeric value. (Impossible de convertir la valeur de texte en valeur numérique.) Could not convert string value to date. (Impossible de convertir la valeur de chaîne en date.) Could not convert floating point value to integer without loss of data. (Impossible de convertir la valeur en virgule flottante en nombre entier sans perte de données.) Cannot rollback transaction - SQL statements in progress. (Impossible d’annuler la transaction - instructions SQL en cours.) Cannot commit transaction - SQL statements in progress. (Impossible d’envoyer la transaction - instructions SQL en cours.) Database table is locked: '%s' (La table de base de données est verrouillée : '%s') Read-only table. (Table en lecture seule.) String or blob too big. (Chaîne ou blob trop long.) Cannot open indexed column for writing. (Impossible d’ouvrir une colonne indexée en écriture.) Cannot open value of type %s. (Impossible d’ouvrir une valeur de type %s.) No such rowid: %s< (Cet ID de ligne n’existe pas : %s<) Object name reserved for internal use: '%s' (Nom d’objet réservé à un usage interne : '%s') View '%s' may not be altered. (Impossible de modifier la vue '%s'.) Default value of column '%s' is not constant. (La valeur par défaut de la colonne '%s' n’est pas constante.) Not authorized to use function '%s' (L’utilisation de la fonction '%s' n’est pas autorisée) Misuse of aggregate function '%s' (Utilisation incorrecte de la fonction d’agrégation '%s') Misuse of aggregate '%s' (Utilisation incorrecte de l’agrégation '%s') No such database: '%s' (Cette base de données n’existe pas : '%s') Table '%s' has no column named '%s' (La table '%s' ne contient pas de colonne nommée '%s') Le pseudo-code AGAL doit commencer par un en-tête de 7 octets : A0 01000000 A1 00 -- for a vertex program A0 01000000 A1 01 -- for a fragment program Décalage
Notice Facile