Introduction à Masapi

Date de publication : 15/07/2008

Masapi est une API en ActionScript 3 qui permet de gérer le multi-chargement de fichier via une application Flash, Flex ou AIR. Bien plus que de simples chargements, cette API permet également de prioriser le chargement des fichiers et de gérer les dépendances entre eux.

Ce tutoriel est une introduction à l'utilisation de Masapi version 1.5 pour charger différents fichiers et les utiliser.

Version PDF (Miroir)

0. Problèmatique
I. Solution
I-A. Chargement en masse (Massive Loading)
I-B. Suivre le chargement
I-C. Récupérer les données
I-D. Divers

0. Problèmatique

La mise en place d'une application/animation Flash/Flex/AIR nécessite souvent que plusieurs fichiers doivent être chargés avant de pouvoir la lancer. Par ailleurs, ActionScript 3 offre différents gestionnaire de chargement (URLLoader, Loader, ...) qui ne fonctionnent pas tout à fait de la même manière suivant quel type de donnée est chargé.

I. Solution

Masapi offre non seulement une vision unifiée des différents gestionnaires de chargement de base (Loader, URLLoader, Sound, URLStream) et permet de gérer le chargement en masse.

I-A. Chargement en masse (Massive Loading)

Il est très simple de mettre en place un gestionnaire de chargement en masse via Masapi. Tout passe par la classe ch.capi.net.CompositeMassLoader :

import ch.capi.net.*;

var cml:CompositeMassLoader = new CompositeMassLoader();
cml.addFile("file.txt"); //utilise un URLLoader avec données de type variables
cml.addFile("anim.swf"); //utilise un Loader
cml.addFile("style.css"); //utilise un URLLoader avec données de type text
cml.start();

Ci-dessus, trois fichiers sont créés et ajoutés dans la liste de chargement puis le chargement est lancé. Le type de fichier est automatiquement déterminé en fonction de l'extension du fichier. Toutefois, il est possible de déterminer manuellement ce type :

import ch.capi.net.*;

var cml:CompositeMassLoader = new CompositeMassLoader();
cml.addFile("file.txt", LoadableFileType.TEXT); //utilise un URLLoader avec données de type text
cml.addFile("anim.swf", LoadableFileType.BINARY); //utilise un URLLoader avec données de type binary
cml.addFile("style.css"); //utilise un URLLoader avec données de type text
cml.start();

I-B. Suivre le chargement

Une fois que le multi-chargement a été lancé, le principal est de savoir ce qui se passe. Masapi gère les événements comme les classes standardes AS3. Pour écouter ce qui se passe, le code se résume à ceci :

import ch.capi.net.*;
import ch.capi.events.*;

var cml:CompositeMassLoader = new CompositeMassLoader();
cml.addFile("file.txt", LoadableFileType.TEXT); //utilise un URLLoader avec données de type text
cml.addFile("anim.swf", LoadableFileType.BINARY); //utilise un URLLoader avec données de type binary
cml.addFile("style.css"); //utilise un URLLoader avec données de type text

cml.massLoader.addEventListener(Event.OPEN, handleOpen);
cml.massLoader.addEventListener(ProgressEvent.PROGRESS, handleProgress);
cml.massLoader.addEventListener(Event.COMPLETE, handleComplete);
cml.massLoader.addEventListener(MassLoadEvent.FILE_OPEN, handleFileOpen);
cml.massLoader.addEventListener(MassLoadEvent.FILE_CLOSE, handleFileClose);

cml.start();

function handleOpen(evt:Event):void { trace("multi-chargement commencé"); }
function handleProgress(evt:ProgressEvent):void { trace("progression : "+cml.massLoader.loadInfo.percentLoaded+"%"); }
function handleComplete(evt:Event):void { trace("multi-chargement terminé"); }
function handleFileOpen(evt:MassLoadEvent):void { trace("ouverture du fichier : "+evt.file); }
function handleFileClose(evt:MassLoadEvent):void { trace("fermeture du fichier : "+evt.file+", status : "+evt.closeEvent); }

Par ailleurs, Masapi gère toute une série d'informations intéressantes concernant l'avancée du chargement.

var cml:CompositeMassLoader = new CompositeMassLoader();
cml.massLoader.addEventListener(ProgressEvent.PROGRESS, handleProgress);
//...

function handleProgress(evt:ProgressEvent):void
{
   var infos:ILoadInfo = cml.massLoader.loadInfo;
   //var infos:ILoadInfo = evt.target.loadInfo; <-- aussi possible
   
   trace("ratio : "+infos.ratioLoaded);
   trace("pourcentage : "+infos.percentLoaded);
   trace("vitesse : "+infos.currentSpeed);
   trace("vitesse moyenne : "+infos.averageSpeed);
   trace("temps écoulé : "+infos.elapsedTime);
   trace("temps restant (estimé) : "+infos.remainingTime);
   trace("bytes chargés : "+infos.bytesLoaded);
   trace("bytes total : "+infos.bytesTotal);
   trace("bytes à charger : "+infos.bytesRemaining);
}

Il est également possible de mettre des écouteurs individuels sur chacun des fichiers, de gérer le nombre de fichiers à charger en même temps, d'éviter le cache et pleins d'autres choses très intéressantes qui ne seront pas approfondies ici. La

documentation des classes de Masapi permet de trouver assez facilement ce que l'on désire.

I-C. Récupérer les données

Une fois le chargement terminé, les données peuvent être facilement récupérées :

import ch.capi.net.*;

/*
Fichiers créés auparavant :
cml.addFile("file.txt", LoadableFileType.TEXT);
cml.addFile("anim.swf", LoadableFileType.BINARY);
cml.addFile("style.css");
*/

var file1:ILoadableFile = cml.getFileAt(0); //récupère file.txt
var data:String = file1.getData(); //récupère les données de file1.txt (simple chaîne de caractère)

var file2:ILoadableFile = cml.getFileAt(1); //récupère anim.swf
var ldr:ByteArray = file2.getData(); //récupère le swf au format binaire

var file3:ILoadableFile = cml.getFileAt(2); //récupère style.css
var css:String = file3.getData(); //récupère le texte de style.css

Etant donné que le type de retour de la méthode getData() peut changer suivant le type de donnée spécifié, Masapi offre également la possibilité de transformer automatiquement les données :

import ch.capi.net.*;

/*
Fichiers créés auparavant :
cml.addFile("file.txt", LoadableFileType.TEXT);
cml.addFile("anim.swf", LoadableFileType.BINARY);
cml.addFile("style.css");
*/

var file1:ILoadableFile = cml.getFileAt(0); //récupère file.txt
var data:URLVariables = file1.getData("flash.net.URLVariables"); //récupère les données de file1.txt dans un URLVariables

var file2:ILoadableFile = cml.getFileAt(1); //récupère anim.swf
var ldr:Loader = file2.getData("flash.display.Loader"); //récupère le swf dans un Loader

var file3:ILoadableFile = cml.getFileAt(2); //récupère style.css
var css:StyleSheet = file3.getData("flash.text.StyleSheet"); //récupère le format dans une instance StyleSheet

Ce mécanisme est très utile, notamment lorsqu'il s'agit de récupérer des fichiers XML sous différents formats.

import ch.capi.net.*;

//...
var file:ILoadablFile = cml.addFile("data.xml");

//...
var rawData:String = file.getData(); //récupération du texte XML
var xmlData:XML = file.getData("XML"); //récupération au format XML
var xmlDoc:XMLDocument = file.getData("flash.xml.XMLDocument"); //récupération au format XMLDocument

I-D. Divers

Masapi possède de nombreuses autres fonctionnalités assez simples à comprendre et utiliser. Il existe plusieurs tutoriels en anglais sur le

site officiel et également d'autres

tutoriaux français, le tout avec des sources d'exemple.

De plus, cette API est libre de droits ! Toutefois, un petit feedback n'est pas de refus, que ce soit pour reporter un bug, proposer une amélioration ou juste donner son avis !

Version PDF (Miroir)

Ce document est à destination de tout le monde