Chargement de fichier en ActionScript 3

Date de publication : 15/05/2007

Par Morgan Loyer (pyrrha.developpez.com)

Découvrez rapidement et simplement comment charger des fichiers en ActionScript 3, qu'ils soient destinés à un affichage ou à une exploitation de données dynamiques. La version alpha de Flash 9, Flex, ou flash CS3 sont requis pour réaliser les exemples de ce cours. Notez que ce cours s'adresse aux débutants et intermédiaires, et qu'il ne prétend pas couvrir l'ensemble des notions évoquées.

Introduction

L'ActionScript 3 (as3) va vous permettre de charger des fichiers de façon plus simple et propre que dans les versions précédentes du langage. Ce cours est composé de trois parties :
- Les classes dont nous aurons besoin pour tout chargement
- Le chargement de fichiers destinés à être exploités.
- Le chargement de fichiers destinés à l'affichage.

1. Les classes indispensables pour charger des fichiers

Ces classes reviennent régulièrement lors de chargement de fichiers en ActionScript 3 et sont souvent indispensables. Il sera nécessaire de connaître par-coeur certaines classes (la classe Event par exemple) si vous souhaitez travailler efficacement.

1-A. La classe flash.net.URLRequest

Cette classe permet le chargement de n'importe quel fichier (texte ou binaire)
En ActionScript 3, nous ne pouvons plus charger un fichier uniquement à partir d'une url formatée en String, il nous faut passer par un objet URLRequest.
Son utilisation est très simple, il nous suffit de créer l'objet et d'y renseigner l'url du fichier en String :

var adresse:URLRequest = new URLRequest("fichiers/exemple.xml");

Pour plus d'informations sur la classe URLRequest, vous pouvez lire la documentation officielle d'Adobe en vous rendant ici

1-B. La classe flash.events.Event et autres classes d'évenements relatifs aux chargements

1-B-1. flash.events.Event

La classe Event se révèle être un des piliers de l'ActionScript 3, car on l'utilise très souvent, pour beaucoup de choses.
Autrefois, lors d'un chargement, nous utilisions par exemple la fonction onLoad() d'un objet LoadVars.
A présent, nous ajoutons un écouteur sur l'objet Loader grâce à la méthode addEventListener(evenement:String, fct:Function). héritée de la classe flash.events.EventDispatcher.
Un autre cours viendra très prochainement informer sur l'utilisation des évènements en ActionScript 3.

Pour récapituler, voici comment on ajoute un écouteur en ActionScript 3 :

// On importe les classes necessaires
import flash.events.Event;

var monObject:MovieClip = new MovieClip (); 
// Notez que la classe Object n'hérite pas de EventDispatcher et ne possède donc pas la méthode addEventListener();
monObject.addEventListener(Event.ENTER_FRAME, onEnterFrame); 
// Event.ENTER_FRAME n'est qu'un exemple d'évènement appliquable, les autres sont détaillés dans le tableau ci-dessous.

// on définie la fonction qui se déclenchera à chaque ENTER_FRAME :
function onEnterFrame (event:Event):void
{
	trace("j'apparait à chaque nouvelle frame ! " + event);
}

Voici un tableau récapitulatif des principaux évènements relatifs aux chargements de la classe Event :

constantes	définition
Event.COMPLETE	se déclenche lorsque le chargement est terminé
Event.UNLOAD	se déclenche lorsque l'objet Loader est vidé de son contenu par la fonction unload()
Event.INIT	se déclenche lors de l'initialisation de l'objet Loader
Event.CLOSE	se déclenche lorsqu'un chargement est stoppé par la fonction close();
Event.OPEN	se déclenche lorsqu'un chargement démarre avec la fonction load();

Pour plus d'informations sur la classe Event, vous pouvez lire la documentation officielle d'Adobe, en vous rendant ici.

1-B-2. flash.events.ProgressEvent

Voyons à présent la classe flash.events.ProgressEvent. C'est elle qui va nous permettre de réaliser des chargements un peu plus poussés, avec par exemple un affichage du chargement en temps réel (preloader).
ProgressEvent est une classe qui hérite de la classe Event, son utilisation ne diffère donc pas de cette dernière.
Je ne vais exposer ici que les évènements qu'offre cette classe, sans exemple, vous en trouverez dans le chapitre "3-Charger un fichier destiné à être affiché".

Constantes	Définitions
ProgressEvent.PROGRESS	se déclenche à chaque fois qu'un paquet de bytes est reçu.

1-C. La classe flash.events.IOErrorEvent et autres classes liées aux erreurs de chargement

L'ActionScript 3 met à votre disposition des classes qui vont servir à gérer les erreurs de chargement, à détailler celles ci...

1-C-1. flash.events.IOErrorEvent

Pour capturer une erreur lors du chargement, vous pouvez utiliser la classe flash.events.IOErrorEvent et définir l'évènement IOErrorEvent.IO_ERROR sur votre objet de chargement.
Ainsi, si une erreur survient la fonction jointe à l'événement sera exécutée, et permettra d'en capturer et détailler les causes.

Voici un tableau récapitulatif de la classe IOErrorEvent :

Constantes	Définitions
IOErrorEvent.IO_ERROR	se déclenche lorsqu'une erreur de chargement se produit

Pour afficher les détails de l'erreur, il vous suffit de faire un trace(); de l'évènement :

function displayError (error:Event):void
{
	trace(error);
}

Ainsi, s'affiche :

[IOErrorEvent type="ioError" bubbles=false cancelable=false eventPhase=2 text="Error #2032: Erreur de flux. URL: file://"]

Voici un tableau explicatif des différents paramètres :

Variable	Description
type	le type de l'évènement
cancelable	Détermine si l'objet d'événement peut être désactivé.
text	Texte à descriptif (message d'erreur) indiquant le numéro de l'erreur, l'url du fichier chargé...

Tout de suite, un exemple un peut plus détaillé de l'utilisation de IOErrorEvent, pour récapituler :

// On import les classes nécessaires :
import flash.events.IOErrorEvent;
import flash.net.URLLoader;
import flash.net.URLRequest;

// on créé notre objet URLLoader
var loader:URLLoader = new URLLoader ();

// on ajoute l'évènement qui déclenchera la fonction indiquerError();
loader.addEventListener(IOErrorEvent.IO_ERROR, indiquerErreur);

// On charge un fichier (qu'importe ici, c'est un exemple !)
loader.load( new URLRequest("texte.txt") );

// on définie la fonction qui se déclenche lors d'une erreur :
function indiquerErreur ( erreur:Event ):void
 {
	trace( "Erreur lors du chargement : "+ erreur );
}

Pour plus d'informations sur la classe IOErrorEvent, vous pouvez lire la documentation officielle d'Adobe, en vous rendant ici

2. Le chargement de fichiers de données

2-A. Définition

La classe flash.net.URLLoader sert à charger des fichiers tels que du texte, des fichiers xml, des pages web. Nous l'utiliserons pour accéder à des données dynamiquement dans notre swf.

2-B. Utilisation

Dans notre exemple, nous souhaitons charger un fichier xml, et récupérer son contenu.
Nous allons donc créer un objet URLLoader, et exécuter sa fonction load, en y spécifiant l'objet URLRequest contenant l'adresse du fichier. Ensuite, il faut ajouter à l'objet URLLoader un événement Event.COMPLETE, qui déclenchera une fonction (par exemple finDuChargement) lorsque le fichier sera chargé.

Comment accéder aux données chargées ?
Dans la définition de la fonction qui sera déclenchée avec l'événement Event.COMPLETE, il vous faut obligatoirement définir un objet de type Event en argument :

function finDuChargement (event:Event):void
{
	// le code ici
};

C'est grâce aux propriétés de cet objet que vous accéderez au contenu du fichier chargé, comme ceci :

function finDuChargement (event:Event):void
{
	var donnees = event.target.data;
	trace(donnees);
};

La propriété target de l'objet Event transmis dans les arguments de la fonction exemple renvoie vers l'objet URLLoader de départ, ainsi, vous pouvez également accéder au contenu du fichier comme ceci :

import flash.net.URLLoader;
import flash.net.URLRequest;
import flash.events.Event;

var loader:URLLoader = new URLLoader ();
loader.addEventListener(Event.COMPLETE, finChargement);
loader.load( new URLRequest("test.txt") );

function finDuChargement (event:Event):void
{
	var donnees = loader.data;
	trace(donnees);
};

Tout de suite, voici un exemple simple de chargement de fichier de données : ( également téléchargeable ici )

// nous importons les classes necessaires :
import flash.events.IOErrorEvent;
import flash.net.URLLoader;
import flash.net.URLRequest;
import flash.events.Event;
import flash.events.ProgressEvent;

// nous déclarons un objet URLLoader :
var chargeur:URLLoader = new URLLoader ();

// nous créons un objet URLRequest qui contient l'url du fichier :
var adresse:URLRequest = new URLRequest ("/fichier/exemple.xml");

// nous lançons le chargement du fichier, en indiquant l'adresse de celui ci par l'objet URLRequest :
chargeur.load(adresse);

// définition des évenements de l'objet chargeur
chargeur.addEventListener(Event.COMPLETE, finDuChargement);
chargeur.addEventListener(ProgressEvent.PROGRESS, avancement);
chargeur.addEventListener(IOErrorEvent.IO_ERROR, indiquerErreur);

// définition de la fonction exécutée par l'événement COMPLETE :
// ( déclenchée lorsque le chargement se termine )
function finDuChargement ( event:Event ) {
	var contenu = event.target.data;
	trace("chargement terminé ! "+contenu);
}

// définition de la fonction exécutée par l'événement PROGRESS :
// déclenchée à chaque avancement du chargement )
function avancement( event:Event) {
	trace(event.target.bytesLoaded+" chargés sur "+event.target.bytesTotal);
}

// fonction indiquant si une erreur de chargmement survient :
function indiquerErreur( event:Event ) {
	trace(event);
}

Notez l'utilisation de l'événement ProgressEvent.PROGRESS de la classe flash.events.ProgressEvent, qui permet de récuperer l'avancement du chargement du fichier en temps réel (expliquée à la partie 1-B-2).

Pour plus d'informations sur la classe URLLoader, vous pouvez lire la documentation officielle d'Adobe, en vous rendant ici

2-C. Contrôler le type de données chargées

2-C-1. Définition

Nous allons voir ici la classe URLLoaderDataFormat. Elle nous permettra de définir le format des données que chargera notre objet URLLoader. Cette classe possède 3 constantes de type String, pour 3 types de données : TEXT = "text", BINARY = "binary", VARIABLES = "variables".

constantes	description
BINARY	indique que les données chargée sont binaires. Ce type permet de charger entre autres des images et les stocker sous forme de tableau de bytes.
TEXT	indique que les données chargées sont du texte
VARIABLES	indique que les données chargées sont des variables

Pour plus d'informations sur la classe URLLoaderDataFormat, vous pouvez lire la documentation officielle d'Adobe en vous rendant ici

2-C-2. Utilisation

Pour informer à notre objet URLLoader le type des données qu'il va devoir charger, nous définissons sa propriété dataFormat.

import flash.net.URLLoaderDataFormat;
import flash.net.URLLoader;

// on définit une variable ayant pour valeur la constante TEXT de la classe URLLoaderDataFormat
var formatDeDonnes:String = URLLoaderDataFormat.TEXT;

var loader = new URLLoader ();
var url = new URLRequest( "texte.txt" );

// on accède et informe la propriété dataFormat de l'objet loader.
loader.dataFormat = formatDeDonnes;
loader.load(url);

3. Charger un fichier destiné à être affiché

3-A. Definition

La classe flash.display.Loader vous permettra de charger des fichiers tels que des SWF, JPG, GIF... Notez son emplacement dans le package flash.display et non le package flash.net comme la classe URLLoader.
Cela est dû au fait que la classe Loader hérite de la classe DisplayObjectContainer, et peut donc être affichée sur la scène avec le contenu qu'elle charge, comme on affiche un movieClip (un autre cours viendra compléter ces notions très prochainement).

3-B. Utilisation

Comment afficher le contenu de l'objet Loader sur la scène ?
Nous allons utiliser la nouvelle fonction addChild. En AS3, les objets graphiques ne sont, par défaut, pas affichés sur la scène; pour les y afficher, il vous faut utiliser la fonction addChild. Nous ne nous étendrons pas sur ce sujet, qui fera l'objet d'un autre cours.
Dans notre cas, pour ajouter le contenu de l'objet Loader sur la scène, nous allons donc programmer :

stage.addChild(loader);

Pour afficher le fichier chargé, contenu dans l'objet Loader.

Voici le code complet : ( également téléchargeable ici )

// import des classes necessaires :
import flash.events.IOErrorEvent;
import flash.display.Loader;
import flash.display.LoaderInfo 
import flash.net.URLRequest;
import flash.events.Event;
import flash.events.ProgressEvent;

// déclaration de notre objet Loader
var chargeur:Loader = new Loader();
chargeur.load(new URLRequest("/fichier/exemple.jpg"));

// on définit les évenements sur la propriété contentLoaderInfo de l'objet loader.
chargeur.contentLoaderInfo.addEventListener(Event.COMPLETE, finDuChargement);
chargeur.contentLoaderInfo.addEventListener(ProgressEvent.PROGRESS, avancement);
chargeur.contentLoaderInfo.addEventListener(IOErrorEvent.IO_ERROR, indiquerErreur);
// on affiche l'objet loader sur la scene :
stage.addChild(chargeur);

// on définit la fonction finDuChargement, executée par l'évenement COMPLETE :
function finDuChargement ( event:Event ) {
	trace("Chargement terminé !");
}

function avancement ( event:Event ) {
	trace(event.target.bytesLoaded+" chargés sur "+event.target.bytesTotal);
}

// fonction indiquant si une erreur de chargmement survient :
function indiquerErreur( event:Event ) {
	trace(event);
}

Notez que les événements ne doivent pas être définis directement sur l'objet Loader, mais sur sa propriété contentLoaderInfo ( retournant un objet LoaderInfo ).

Cet exemple regroupe quelques notions expliquées dans le chapitre 2-Charger un fichier pour exploiter ses données. Vous pouvez ensuite décharger votre objet Loader pour libérer de la mémoire, pour cela utilisez la fonction unload() sur l'objet.

loader.unload();

Si vous souhaitez déclencher une fonction lors d'un unload d'objet Loader, notez l'existence de l'événement Event.UNLOAD.

Pour plus d'informations sur les classes Loader et LoaderInfo, vous pouvez lire la documentation officiel d'Adobe :
en vous rendant ici pour la classe Loader
en vous rendant ici pour la classe LoaderInfo

3-C. La fonction Loader.loadBytes

3-C-1. Définition

La fonction loadBytes de la classe Loader va vous permettre de charger dans l'objet Loader des données binaires. Ces dernières pourront être obtenues avec la classe URLLoader par exemple, en informant sa propriété dataFormat avec la constante BINARY de la classe URLLoaderDataFormat ( voir chapitre 2-C ).

3-C-2. Utilisation

Nous allons prendre pour exemple un cas simple, imaginons que nous voulons garder une image en cache, puis l'afficher dans un objet Loader. La première étape est de charger l'image avec URLLoader, en prenant soin de préciser le type BINARY. Nous chargerons ensuite les données de l'objet URLLoader avec la fonction loadBytes de la classe Loader.

Voici un exemple de code ( également téléchargeable ici )

// import des classes nécessaires :
// nous importons les classes necessaires :
import flash.net.URLLoader;
import flash.net.URLRequest;
import flash.net.URLLoaderDataFormat;
import flash.display.Loader;
import flash.display.LoaderInfo;
import flash.events.Event;
import flash.events.ProgressEvent;
import flash.events.IOErrorEvent;

// nous déclarons un objet URLLoader :
var chargeur:URLLoader = new URLLoader ();

// nous créons un objet URLRequest qui contient l'url du fichier :
var adresse:URLRequest = new URLRequest ("image.jpg");

// nous lançons le chargement du fichier, en indiquant l'adresse de celui ci par l'objet URLRequest :
chargeur.dataFormat = URLLoaderDataFormat.BINARY;
chargeur.load(adresse);

// définition des événements de l'objet chargeur
chargeur.addEventListener(Event.COMPLETE, finDuChargement);
chargeur.addEventListener(ProgressEvent.PROGRESS, avancement);
chargeur.addEventListener(IOErrorEvent.IO_ERROR, indiquerErreur);

// définition de la fonction éxecutée par l'événement COMPLETE :
// ( déclenchée lorsque le chargement se termine )
function finDuChargement ( event:Event ) {
	var contenu = event.target.data;
	creerLoader (contenu);
}

// fonction déclenchée à la fin du chargement URLLoader, qui ajoute un Loader sur la scene :
function creerLoader ( datas ) {
		var chargeur:Loader = new Loader();
		chargeur.loadBytes(datas);
		stage.addChild(chargeur);
}

// définition de la fonction éxecutée par l'événement PROGRESS :
// déclenchée à chaque avancement du chargement )
function avancement( event:Event) {
	trace(event.target.bytesLoaded+" chargés sur "+event.target.bytesTotal);
}

// fonction indiquant si une erreur de chargmement survient :
function indiquerErreur( event:Event ) {
	trace(event);
}

4. Conclusion

Ce cours touche à sa fin. Il est probable que je le complète ou que je le modifie prochainement, avec la sortie de flash CS3.
Pour toute question technique, de compréhension, d'aide, je vous demande de la poser sur le forum, je serais contraint de ne pas vous répondre sur mon mail par manque de temps.
Pour toute remarque, suggestion, correction, n'hésitez pas à me joindre en cliquant ici ou par message privé.

Ce document est issu de http://www.developpez.com et reste la propriété exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise à l'obtention préalable de l'autorisation de l'auteur.